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A method and apparatus that uses a hyper- 
media approach to managing distributed objects. 
A first embodiment of the present invention uses 
the World Wide Web hypermedia system. A 
user initializes browser software that allows the 
user to browse and change various attributes of 
objects in the system. The browser communi- 
cates with a server that includes an http adapter 
and a gateway. The gateway can access ob- 
jects in the system and generate HTML code 
in accordance with the objects. One embodi- 
ment of the present invention uses hierarchical 
tree-oriented objects. These objects are "self- 
describing" (also called "introspective"). The 
server queries the objects in response to the 
queries from the browser and each, queried ob- 
ject responds with information about itself. In 
another preferred embodiment, the server initi- 
ates queries of the objects and retains this in- 
formation for use in responding to later queries 
from the browser. 
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HYPERMEDIA OBJECT MANAGEMENT 

FIELD OF THE INVENTION 

This application relates to object oriented programming and, in 
particular, to management of distributed objects via the World Wide Web. 
BACKGROUND OF THE INVENTION 

The past several years have seen an explosive growth of the use of 
distributed objects. Now, a single system may be composed of objects 
obtained from different vendors and having different interfaces. Such objects 
are called "heterogeneous objects." Thus, a system can be formed of a large 
and rapidly changing number of heterogeneous objects. Such a system 
requires a flexible and adaptive approach for system and application 
management. Conventionally, a heterogeneous system is managed by way of 
object-specific presentation facilities, i.e., by way of a user front-end that was 
written for each type of heterogeneous object. Such an approach is, however, 
too expensive in both development time and maintenance and administrative 
costs. In addition, conventional object management is often achieved through 
a single management center. Use of a single center is not efficient when a 
large number of objects need to be managed. 
SUMMARY OF THE INVENTION 

The present invention overcomes the problems and disadvantages of 
the prior art by using a hypermedia approach to object management. In this 
approach, each object is akin to a hypermedia document. The described 
embodiment of the present invention uses the World Wide Web hypermedia 
system. In a preferred embodiment of the present invention, a user initializes 
browser software that allows the user to browse and change various attributes 
of objects in the system. The browser communicates with a server that 
includes an http adapter and a gateway. The gateway can access objects in 
the system and generate HTML code in accordance With the* objects. 

A described embodiment of the present invention uses hierarchical tree- 
oriented objects. In a first embodiment, these objects are "self-describing" 
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(also called "introspective"). The server queries the objects in response to the 
queries from the browser and each queried object responds with information 
about itself. In another preferred embodiment, the server initiates queries of 
the objects and retains this information for use in responding to later queries 
from the browser. 

In accordance with the purpose of the invention, as embodied and 
broadly described herein the invention is a system for managing objects, 
including a first server, comprising: a first receiver portion configured to 
receive a request in a hypermedia format; a first translator portion configured to 
convert the hypermedia request to an object request;a sender portion 
configured to send the object request to an object manager; a second receiver 
portion configured to receive a response from the object manager; and a 
second translator portion configured to convert the object manager response to 
the hypermedia format. 

In further accordance with the purpose of this invention, as embodied 
and broadly described herein the invention is a method for browsing objects, 
where a browser communicates with a server, comprising the steps, performed 
by the browser, of: sending an initial URL to the server; receiving first data 
from the server, where the first data specifies an object corresponding to the 
URL; sending user-entered data associated with the object to the server; and 
receiving second data from the server, where the second data specifies a 
second object corresponding to the user-entered data. 

Advantages of the invention will be set forth in part in the description 
which follows and in part will be obvious from the description or may be 
learned by practice of the invention. The advantages of the invention will be 
realized and attained by means of the elements and combinations particularly 
pointed out in the appended claims and equivalents. 
BRflEF DES CRBPTIOM OF THE DRAWIMfiiS 

The accompanying drawings, which are incorporated in and constitute 
a part of this specification, illustrate several embodiments of the invention and, 
together with the description, serve to explain the principles of the invention. 
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Fig. 1 is a block diagram of a computer system in accordance with a 
preferred embodiment of the present invention. 

Fig. 2 is another block diagram of a computer system in accordance 
with a preferred embodiment of the present invention. 

Fig. 3 is a diagram of data sent between a browser, server, and object 
manager in accordance with the embodiment of Fig. 1. 

Fig. 4 is a diagram of a format in which objects are organized. 

Fig. 5 shows another example of a page displayed by the browser. 

Figs. 6(a) and 6(b) show an example of HTML that causes the browser 
to display a portion of the page of Fig. 5. 

Figs. 7(a) through 7(c) show further examples of HTML that result in 
the portions of page of Fig. 5. 

Figs. 8(a) and 8(b) show several examples of ORM (Object Resource 
Management) requests made by the server to the object manager and the 
resulting responses from the object manager. 

Fig. 9 shows another page displayed by the browser. 

Fig. 10 shows layers of functions available to the object manager. 
DETAILED DESCRIPTION OF PREFERRED EMBODIMENTS 

Reference will now be made in detail to a preferred embodiment of the 
invention, an example of which is illustrated in the accompanying drawings. 
Wherever possible, the same reference numbers will be used throughout the 
drawings to refer to the same or like parts. 
I. System Overview 

Fig. 1 is a block diagram of a computer system 100 in accordance with 
a preferred embodiment of the present invention. Computer system 100 
includes a first computer 110 and a second computer 120. First computer 1 10 
and second computer 120 are connected together via line 106, which can be, 
for example, a LAN, a WAN, or an internet connection. Line 106 can also 
represent a wireless connection, such as, a cellular network connection. . 

First computer 110 includes a CPU 102; a memory 104; input/output 
lines 105; an input device 160, such as a keyboard or mouse; and a display 
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devce 150, such as a display terminal. First computer 110 also includes an 
■nput device 161 that reads computer instructions stored on computer readable 
medium 162. These instructions are the instructions of e.g., browser software 
130. Memory 104 of first computer 110 inc.udes browser software 130 
Hypertext Markup Language (HTML) 135, and objects 132. A person or 
ordinary skill in the art will understand that memory 104 also contains 
additional information, such as application programs, operating systems, data, 
etc., which are not shown in the figure for the sake of clarity. 

Second computer 120 includes a CPU 102' and a memory 104' 
Memory 104' of second computer 120 includes server software 140, an object 
manager (ORM) 142, and objects 144. HTML 135 in the memory of first 
computer 110 was downloaded over line 106 from server 140 of second 
computer 120. A person of ordinary ski., in the art will understand that 
memory 104' also contains additiona. information, such as application 
programs, operating systems, data, etc., which are not shown in the figure for 
the sake of clarity. Server 140, object manager 142, and objects 144 can also 
be located in memory 1 04 of first computer 1 10. 

It will be understood by a person of ordinary skill in the art that 
computer system 100 can also include numerous elements not shown in the 
F,gure for the sake of clarity, such as disk drives, keyboards, display devices 
network connections, additional memory, additional CPUs, LANs, input/output 
lines, etc. 



The following paragraphs provide a general discussion of the World 
Wide Web ("the Web"). The Web is built around a network of "server- 
computers, such as second computer 120, which exchange requests and data 
wth each other using the hypertext transfer protocol ("http"). A human 
designer designs the layout of a Web page, which is then specified using HTML 
("Hypertext Markup Language",. Several versions of HTML are currently in 
ex.stence. Examples include HTML versions 2.0 and 3.0, a* specified by the 
WWW Consortium of MIT. The HTML used in the described embodiment of 
the invention inc.udes frames, forms, and tables, as are known to persons of 
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5 ordinary skill in the art. 

A user views a Web page using one of a number of commercially 
available "browser" programs. The browser submits an appropriate http 
request to establish a communications link with a Web server of the network. 
A typical http request references a Web page by its unique Uniform Resource 
10 Locator ("URL"). A URL identifies the Web server hosting that Web page, so 

that an http request for access to the Web page can be routed to the 
appropriate Web server for handling. Web pages can also be linked graphically 
to each other. 

Fig. 2 is an additional block diagram of a computer system in 

15 accordance with a preferred embodiment of the present invention. Browser 

130 communicates with server 140. Server 140 includes an http adapter 202 
and a management gateway 204. Http Adapter 202 handles communication 
via the known http protocol. Management gateway 204 communicates with 
object manager 142. Server 140 communicates with one or more objects 132, 

20 144 using a request/response (RR) protocol, such as the ORM (Object Resource 

Management) protocol, which is discussed below. Note that objects 132 and 
144 can be located on the same or different physical computers or machines. 
Server 140 also communicates with external interface 206, which 
communicates using the known SNMP and CMIP protocols. Server 140 also 

25 communicates with external gateway 208, which communicates using the 

known SNMP and CMIP protocols. The system can contain more than one 
servers 140 and more objects than are shown in Fig. 4. 

Fig. 3 is a diagram of data sent between a browser, server, and object 
manager in accordance with the embodiment of Fig. 1 . In the example of Fig. 

30 3, the user has already begun execution of browser software 130. In step 

302, the user enters the URL of server 140 by way of browser 130. The 
browser sends a request to the server and, in step 304, the server responds 
with the HTML to generate a home page. The home page allows the user to 
enter a URL (or to chose a URL from those known provided within the HTML of 

35 the home page). The user can then chose to set/browse objects in the system, 
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as described below. The user can also request information and statistics about 
once or more objects in the system. 

In step 306, the user enters a URL of an object by way of browser 
130. Server 140 converts the URL to a request to an object manager. For 
example, in the described embodiment, server 140 converts the URL to an 
ORM request, as described below. The ORM request is sent to the object 
manager, which returns object data in steps 308 and 310. Server 140 
converts the object data into HTML, which is sent to browser 130 in step 312. 
The HTML may be based on a predetermined page template known to the 
server. Alternately, the format of a page may be determined "on the fly" based 
on the information obtained from the object manager. Server 1 40 converts all 
pathnames, such as object-links in the object data (see Fig. 4) to URLs in HTML 
and vice versa. Thus, if a user clicks on an area in a page displayed by the 
browser that corresponds to an object-link, browser 130 has the URL 
corresponding to that object-link. This new URL is sent to the server, which 
obtains the page information and sends HTML to display information for the 
object connected to the object-link. 

Steps 314 through 320 represent a "set" mode, in which the user 
enters new values for an object by way of browser 130. In step 314, the user 
indicates that he wishes to enter "set" mode. This indication is usually 
accomplished by clicking on a button in the current page (thus, the HTML 
generated by server 140 should include HTML for this button). In step 316, 
server 140 sends a "form" for set mode. In step 318, the user enters new 
values into the form and clicks on "submit" (or "apply", (see Fig. 5), as is 
known to persons of ordinary skill in the art. Server 140 converts the 
submitted form to, for example, an ORM request, as described below. The 
ORM request is sent to the object manager, which returns object data in steps 
317 and 319. Server 140 converts the object data of step 319 into HTML, 
which is sent to browser 1 30 in step 320. 

Steps 322 through 332 represent a "browse" mode, in which the user 
views values associated with an object by way of browser 1 30. In step 322, 
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the user indicates that he wishes to enter "browse" mode. This indication is 
usually accomplished by clicking on a button in the current page (thus, the 
HTML generated by server 140 should include HTML for this button). In step 
324, server 140 sends a "form" for browse mode. In step 326, the user 
enters new values into the form and clicks on "submit" (or "apply", see Fig. 5), 
as is known to persons of ordinary skill in the art. Server 140 converts the 
submitted form to f for example, an ORM request, as described below. The 
ORM request is sent to the object manager, which returns data corresponding 
to the object in steps 328 and 330. Server 140 converts the response of step 
330 into HTML, which is sent to browser 130 in step 332. 

II. Hypermedia Object Management 

A. Object Organization 

Fig. 4 is a diagram of a format in which objects are organized in a 
preferred embodiment. This organization is transparent to server 140 and 
browser 1 30. It will be understood that the present invention can be used with 
a number of object organizations and with a number of object management 
protocols. The embodiment described herein uses the ORM protocol, as 
described below. 

The model of Fig. 4 assumes the following: 

1) Management operations can be mapped to two basic operations: 
a) Get an attribute (or a set of attributes) of an object and b) set an attribute 
(or set of attributes) of an object. 

2) All entities to be managed can be organized as a directed tree with 
nodes and leaves where the nodes are either (callable) objects or components 
(sub-parts of objects) with attributes as the leaves (with combined name/pair 
values), and 

3) All knowledge about management operations and attributes is built 
into and controlled by the managed object. 

Fig. 4 shows the following types of entities: 
1 ) Objects 

Objects encapsulate and control management aspects and respective 
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management operations. In the described embodiment, an object is identified 
by a "pathname," which is the destination for object calls. Each manageable 
object has its own virtual tree of components, attributes, and object-links. 

2) Components 

Components are the primary structuring mechanism within an object. 
Component sub-trees may be of arbitrary depth and component nodes may 
contain any number of object-links, other sub-components, or attributes. 

3) Attributes 

Attributes describe specific aspects of a component within an object 
(for example, "status = running" describes the state of a resource). Attribute 
nodes have additional properties beyond name and value, such s access mode 
and data type. Attribute nodes are leaves and do not have children. 

4) Object-links 

Object-links contain an object reference to a related object. As every 
object is responsible for its own virtual tree of resources, one object can 
provide a reference (hyperlink) to another object. Thus, in the described 
embodiment, a first object can have links to a second object, so that objects 
can be "walked" by way of browser 130. 

5) Relations 

Objects and components are the primary means for structuring and 
navigation in the described embodiment. Attributes have values that 
characterize the state of the resource. All operations (browsing and attribute 
retrieval/setting) are performed with respect to a single level of the tree (e.g., 
relative to a specific parent). 

Server 1 40 preferably issues the following requests to object manager 

142: 

1 ) Get a list of linked objects, 

2) Get a list of components and/or sub-components, 

3) Get a list of attributes, 

4) Set a list of attributes (Along with name/value pairs for each 
attribute), and 
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5) Get an extended list of attributes, which returns meta-information 
about the attribute, such as data type, allowed access mode (ro, rw) or valid 
ranges of new attribute values. Within the ORM model, all management 
operations are mapped to these five operations. Thus, every managed object 
preferably supports these five operations. 

It should be understood that the attributes and object types shown in 
the examples herein are included only for the purposes of example. The 
present invention can be practiced using any appropriate object organization 
and type. 

B. Server Interface 

In the described embodiment, all messages passing in and out of server 
140 are ASCII messages. 

A example URL for object 402 of Fig. 4 would look like: 
Http://ham/get/objectRoot/Component1 /Component2/ 

A example URL for attribute 404 of Fig. 4 would look like: 
Http://ham/get/objectRoot/Component1 /Component2/Attrl / 

In both of these URLs, "ham" stands for "HyperMedia Adapter to 
Management" and represents the address of server 140; "get" (this could also 
be "set") represents an operation to be performed on an object or attribute; and 
the remainder of the URL represents the tree of the object or attribute known 
to the object manager. Other URLs may also include additional information 
use, for example, by the object manager. 

Fig. 5 shows a page displayed by browser 1 30 in "set" mode. Fig. 5 
shows the values of attributes for a "Configuration" object component. These 
attributes include: 

1) Status 520, 

2) Maximum Concurrency 523, 

3) Trace Level 524, 

4) OSL Traces Enabled 526, 

5) Script directory /Vol. 528, 

6) Script File 530, 

9 
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5 7) Cache Tel Scripts 532, 

8) Tel Trace Enabled 534, and 

9) Maximum Size of Synthesized Page 536. 

Fig. 5 also shows an entry 522 for changing the status attribute. It 
should be understood that the attributes of Fig. 5 are presented for the sake of 
10 example only and are not to be taken in a limiting sense. Fig. 5 also shows a 

reset button 540 and an apply button 550. When the user clicks reset button, 
original attribute values are returned. When apply button 550 is clicked, 
browser 1 30 posts a form, as is known to persons of ordinary skill in the art. 

Figs. 6(a) and 6{b) show an example of HTML generated by server 140. 
is When browser 130 interprets the HTML of Fig. 6, it generates the portion 

containing attribute values 520-536 and buttons 540, 550 of Fig. 5. Figs. 7(a) 
through 7(c) show an example of HTML generated by server 140. When 
browser 130 interprets the HTML 702, 704, and 706 of Figs. 7(a) through 
7(c), it generates portions 502, 506, and 504, respectively, of Fig. 5. 

Fig. 9 shows another page displayed by browser 130 in accordance 
with HTML generated by server 140. The page of Fig. 9 is used to browse 
objects, but cannot change the attributes of objects. 

The previous paragraphs discuss the browser GUI presented to the user 
and how server 140 translates between HTML and a protocol understood by 
the object manager. The following paragraphs describe the protocol used to 
communicate with object manager 142 about objects and to change objects in - 
accordance with the HTML received by the server. 

Figs. 8(a) and 8(b) show several examples of ORM requests made by 
the server 1 40 to object manager 1 42 and the resulting responses from object 
30 manager 142. Pages of the description shows formats of such requests 

and responses. Request 802 is an example of an OrmGet request sent from 
server 140 to object manager 142. The format of an OrmGet request is: 
OrmGet: pathname 
entity types 

where pathname is a name of an object or an attribute. Possible entity types 
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are: "Object" (all known objects at this level), "Component" (a list of all 
components below the level of the path specified in the OrmGet), "Attribute" (a 
list of attributes for the current node; for every attribute, its name and 
"stringified value is returned; if the pathname already navigates to an attribute, 
the object manager returns the empty string), "Info" (returns "meta-attributes" 
such as mode, range and unit), and <none> (i.e., an empty string). 

In request 802 of Fig. 8, the server "knows" about an object 
"HyperMedia Adapter NSK", possibly from receiving a URL from browser 130. 
Line 820 represents a version of the server (e.g., version 1 .0). Line 822 is an 
"OrmGet" request for object "HyperMedia Adapter NSK". Server 140 requests 
information from object manager 142 about entity types (Info), Component, 
and Object (lines 824). 

Response 804 is generated by object manager 142 and sent to server 
140. The object has four components, no info, and no objects at the same 
level. As seen in step 312 of Fig. 3, server 140 generates HTML 604 of Fig. 
7(c) in accordance with response 804 and sends the generated HTML to 
browser 1 30. 

Assuming that the user wants to browse information about the 
Configuration component of object "HyperMedia Adapter NSK", browser 130 
sends a request to server 140 to this effect. Server 140 then sends request 
806 to the object manager, which responds with response 808. Request 806 
is similar to request 802, but the pathname in line 830 is "HyperMedia 
Adapter NSK/Configuration". 

Response 808 includes attributes for the "Info" entity. Thus, the 
response includes an attribute value, mode, field, and range for each of ten 
attributes of the component "Configuration". As seen in step 332 of Fig. 3, 
server 140 generates the HTML of Figs. 6(a) and 6(b) in accordance with 
response 808 and sends the generated HTML to browser 130 (see Fig. 5). 

Assuming that the user wants to change one or more attributes of the 
Configuration component of object "HyperMedia Adapter NSK", browser 130 
sends a request to server 140 to this effect (assuming that the browser is in 

11 
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5 "set" mode). Server 140 then sends request 810 to the object manager, 

which responds by sending a status value (not shown). 
A format of the OrmSet request is: 
OrmSet: pathname 
Attribute: name 
io Value: val 

where "name" and "val" respectively, represent an attribute name and an 
attribute value. This command is shown in line 840. The command can 
include more than one Attribute/Value pairs. 

In the example, request 810 specifies new values for eight attributes of 
is component "Configuration." Assuming that no error occurs when the object 

manager changes the attribute values, server 140 generates HTML reflecting 
the new attribute values in accordance with the response and sends the 
generated HTML to browser 130 {not shown). 

A preferred embodiment of the present invention has a server that 
20 interfaces with "self describing" (or "introspective") objects. The server sends 

requests to and receives responses from an ORM (Object Resource Manager). 
The system may include more than one ORM and more than one server. Each 
server may "know" about zero or more ORMs. Thus, the system is not 
centralized and does not necessarily depend on a central point to interface with 
25 the objects. 

C. The Object Manager 

1 . Self Describing Objects 
Fig. 4 shows an example of object organization in a preferred 
embodiment of the present invention. Pages of the description, shows 

examples of an ORM Server Support Library API (Application Program 
Interface) supported by the object manager to access objects in a preferred 
embodiment of the present invention. The routines in the API of pages are 
used by object manager (e.g., ORM 142 of Fig. 1) to receive requests f/om 
server 140 and to prepare responses to the requests. It will be understood be 
persons of ordinary skill in the art that any object manager can be used in 
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conjunction with the present invention, as long as the object manager is 
capable of communicating with server 140 and of fulfilling GetOrm and SetOrm 
requests from server 140. 

Fig. 10 shows layers of functions available to the object manager. A 
Protocol layer 1002 handles the ORM protocol, e.g., decodes the request from 
server 140, initiates the corresponding functions, and assembles an ORM 
response. Protocol layer 1002 is the lowest layer and drives all calls to the 
upper layers by calling "registered" functions. A Node layer 1004 handles 
navigation between nodes, ie.e, parsing the pathname to locate the virtual 
node, which represents some management entity. 

A Handle layer 1006 maps "virtual nodes" to real objects/data. Such a 
mapping results in a "handle." Handles are explicitly requested and released. 
An Aspects layer 1008 handles instances that are made up from more than one 
ORM tree. For example, the "statistics" Component is not a single Component 
n the tree, but is generated by the object manager. As another example, some 
attributes depend on others and cannot be modified independently, but have to 
be treated as a single, atomic operation. These groups of attributes within an 
instance are called "aspects" and the corresponding Aspect layer is provided to 
extract and modify groups of attributes within an instance. 

An Attribute layer 1010 retrieves or updates a single attribute (of an 
aspect) and provides the meta information corresponding to this attribute. A 
Conversion layer handles the actual conversion of attributes between the 
external (ORM) and the internal (native) presentation. This layer also converts 
states and bitmaps to "friendly strings." 

2. Web Agents 

In another preferred embodiment of the present invention, the objects 
are not self-describing. In such an embodiment, one or more servers 140 in 
the system performs a "worm" function, i.e., one or more servers 140 follow 
object-links between objects and save all the information available concerning 
those objects. When a request is received from browser 130, server 140 
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5 sends its collected data to browser 1 30 (assuming that the collected data is 

not older than a threshold age value). 

In summary, the present invention allows a user to manage objects by 
way of hypermedia, such as the world wide web. In a preferred embodiment, 
the objects are self-describing and respond to questions about themselves from 

.10 one or more object managers. A server communicates with the object 

manager(s) and generates HTML from responses received from the object 
manager. Conventional browser software allows a user to indicate which 
objects he wishes to browse or change. Using a conventional hypermedia 
request/response protocol, the browser and server communicate to obtain 

15 information about objects and their attributes. The server also translates 

HTML/URLs received from the browser to requests to the object manager. 
Such a system allows a non-centralized object management system. 

Other embodiments will be apparent to those skilled in the art from 
consideration of the specification and practice of the invention disclosed herein. 

20 It is intended that the specification and examples be considered as exemplary 

only, with a true scope of the invention being indicated by the following claims 
and equivalents. 
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Browse (readonly) and Change (read write) modes axe differentiated by different 
URL s For the Change mode an HTML input form is created with user interface ele- 
ments dependant on the meta information provided with attributes. Dependant 
from this meta information, simple text input-or numeric input fields, popup boxes 
or radio buttons are generated. 

A submit of this HTML form results in an HTTP POST request, which appears at the 
managements adapter with a special URL and the list of name/value pairs from the 
input form. These values can be checked against the information now retrieved from 
the object (see above) and a ORM SetAttribute request is send to the respective 
object This object initiates the intended state changes or returns an error to the 
adapter, which then creates a new page, which reflects the outcome of the operation. 
Access control can be either applied by the generic HTTP adapter, filtering POST 
methods for example or by the called object itself using principal identifiers in the 
ORM request. 



5.3 Events and Alerts 

Compared to SNMP or CMIP ORM has no event or trap mechanism. With this respect it 
,s much closer to the NSK management protocol called SPI. Instead event and alert sup- 
port is provided by another mechanism (and object) within MSF, called Alert Faahty, 
which is built on top of the Common Execution Environment (CEE). 
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6.0 ORM Protocol 

6.1 General Characteristics 

The ORM protocol is a simple request response protocol constructed out of lines of ASCII 
text and terminated by newline, to browse through the managed object and change its 
state. In this way, it is directly comparable to the HTTP protocol 

it is bytes tream oriented, as it contains no length Eelds or has any fixed structure, but the 
individual items are separated by special characters, i.e. colons and newiines. 

The logical end of a protocol unit is determined by an empty line Le. a line with a newline 
character as the first character. 

Remark: The decision for a pure ASCII protocol may be surprising, as MSF has a well 
defined presentation layer/ protocol by rDL/PCU/GLU, but ORM is designed to support 
self contained object management, e.g. all manageable aspects of an object should be 
described by the managed object (or its manager) itself and just known by it. This 
implies, that a lot of human readable information has to be shipped with this protocol 
and using a pure ASCII protocol seemed quite natural. In addition the browsing nature of " 
the protocol would have resulted in a quite unhandy IDL structure of unbounded 
sequences of any's or unbounded strings, probably with another layer of unbounded 
types above. Using ASCII strings simplifies the creation of protocol units. Last not least 
ORM must also support the entities provided to build the MSF infrastructure itself e e ' 
must also be available with and without these execution environments. ' 

Internally the ORM protocol (ORM-P) is a tagged line protocol, as every line starts with a 
tag word followed by the tag value separated by a colon and terminated by an end of line 
f*T^^tm?imexmepmtti im^mppbmmmtm^^ consorted requests) 
Errors are reported inline with the data i.e., where they occur, by special error tags. 

and ^P 0 ™* constructed the same way and the response is merely a 

filledout" or -completed" request and as such, the information in it is self describing 
(i.e. need not necessarily correlated with the request). This is not true for authentication 
information, which is not mirrored in the response. 

The ORM-P basically supports two kinds of operations: 

1 . get entities (OnnGet) 

2. set attributes (OrmSet). 

The two keywords OnnGet and OrmSet at the beginning of every sub-request describe 
the intended operation (Le. are the operation tags). 

!T fi?™w° tWO basic °P erations ttere is a preamble required for every (consoli- 
dated) ORM packet, identifying the originators protocol version (tag OrmVersion) and in 
tne case of a request, there is an optional tag, to pass authentication information from the 
client to the server (OrmWho). 
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6.2 Pathnames: 

Pathnames provide the necessary navigation and identification information to locate a 
specific aspect of an object (or its internal entities). The different parts of the pathname 
usually axe also the names of the entities in the generated user interface and as such, 
should be "friendly", descriptive names. 

A pathname consists of a V separated list of components, which in turn may contain 
any printable character including whitespace. 

For the current version, characters in the pathname components are restricted to the 
printable set of ASCII characters but may be extended to cover ail printable ISO-8859-1 
characters in the future (ORM-P is "8-bit dean", but this restriction is just to be more flex- 
ible in the choice of user interface construction). 

There are two special component names, which follow the POSDC convention for filesys- 
tem tree navigation: - * and These are only allowed in conjunction with an OnnPath 
tag and refer to the current node and to the parent of the current node respectively, where 
the "current node" must have been defined by a previous ORM sub-request in the same 
protocol unit (i.e. OrmCet or OrmSet). An attempt to traverse the parent of the root of the 
tree is treated as an erroneous pathname (compare with "cd" in a POSDC system). 

6.3 Error Reporting (OnxiError): 

Errors are reported, where they are detected, i.e. the error tag (OrmError) usually appears 
directly behind the error causing tag in the response. This allows some kind of identifica- 
tion of the failed subrequest or protocol item even for large consolidated requests. 

An error tag in the response also indicates, where the request was aborted. Previous sub- 
requests in the same ORM packet may have been processed 1 . An error tag (OrmError) 
has a constant and a variable part where the constant part identifies the kind of error, the 
variable part is used for additional hints, what caused the error. As the error is reported 
with a context, this context provides valuable information for error explanations. 

The Format of an error protocol item: 

OrmError : <decimal errorcode> <stringcode> : <variable part* \n* 



6.4 Version Support Orm Version: 

The first line in every protocol unit must identify the highest protocol version number, 
this protocol unit complies to. The actual version is 1.0! 



1 . When the ORM requests are issued via the IDL interface, the error also appears as an exception with the 
exception detail showing the actual ORM error code. 
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eg- 



OnnVersion : <ma jor> . <minor> 



A server/application may respond to this request with an error VersionMiss match fol- 
lowed by its desired version id. 

6.4.1 Protocol Conformance 4c Protocol Errors: 

Unknown tags should be ignored unless they appear at a position, where another tag is 
required (an attribute tag must be followed by a value tag for example). If the latter 
occurs, the unidentified or unexpected tag is placed in the response message followed bv 
an error tag with "Pro tocolFailure " 7 

6*5 Principal Identification Information: OrmWho 

For the purpose of propagating the identification of a principal causing the request or to 
be used with the request ORM-P supports a protocol item to ship any kind of (encoded) 
principal identifier with a request in the following way: 

OrmWho: <principal identifiers 

Up to now, neither the <id-scheme> nor the encoding or interpretation of the "encoded- 
pnnapal-identifier'' are specified in any detail by ORM-P but are up to the application 
and require an agreement between the ORM-P client and server. This may be subject of 
change! 

6.6 Browse Operation; OrmGet 

The operation tag "OrmGet'' has to be followed by a colon - the tag separator) and 

SSl"? ? b T * M I athn T' ^ ORM P rotoc ° l thlop^ation tag fol- 
lowed by the optional pathname has to be terminated by a newline character. This first 
line is followed by a list of entity type speofyers requested. 

6.6.1 Entity Types 

The OrmGet request is followed by a list of type speofyers to describe the kinds of entities 
requested for browsing. Allowed types (and entity speofyers) are: 

• Object 

requests a list of all known object links at this level. A friendly name and the link- 
address (NOR) is returned per object 

• Component 

A list of all components below the level of the path specified in the GET line is 
requested. A list of names is returned. 

• Attribute 
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A list of attributes for the current node is requested. For every attribute its name 
{Name:<name>) and its stringified value (Va/i*;<value) is returned. If the path in the 
OrmGet line already navigates to a single attribute, the returned name is the empty 
string. 

♦ Info (implies Attributes) 

This type addresses the same type of entities as "Attributes", but here meta informa- 
tion in addibon to the name /value pair is requested, as there is Field for identifying 
the type of input expected, Mode to describe the access mode (read, read-write or 
write) and the so called hints (Range and Unit), which can be used by the user-interface 
to generate a more sophisticated presentation of the attribute. These info fields are 
described below in detail in the response section. 

• <Empty> 

An empty type specifyer indicates that the validity of the pathname should be 
checked, but no information is requested. 

As all ORM protocol items, every single type specifyer is terminated by a newline. 
Examples: 

DOrmGet: /telnet/ windows \n 
Component \n 
\n 

2 ) OnnSet: / telnet /windows/ #ptyl/status\n 
Attribute\n 

OrmPath: . . / . . /pty2/status\n 

AttributeNn 

\n 

3) OrmGet : /telnet\n 
Object\n 
Component \n 
Info\n 

\n 

Note: Leading blanks in front of the tag or the tag value are ignored as well as lines, 
whose first character is a ~#". 

The OrmGet request may be called without a pathname specification (e.g. "OrmGefcXn") 
in which case the root object itself is referenced and the only valid type specifyer is 
-Object", which will return the "friendly" name of this object manger and its link address 
(Note; this link address may be another one, as the request was sent to, ix. this allows 
redirecting the management requests to another object reference). 

6.6.2 OrmGet Response 

The response to a OrmGet request merely mirrors the request, but here the type specifyers 
are used as tags (to type the following entity) followed by the name of the entity (sepa- 
rated by ~:~) followed by a newline character. The name item is followed by a type 
dependent list of additional tagged items, describing further properties of this entity. 

Although the partial responses below are listed per entity type, they appear in the same 
response unit in the same sequence as in the corresponding request unit, Le. if the latter 
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requested entity types by the sequence "Object\nComponent\Attribute\n w / then the 
response will first list all available objects at this level followed by all available compo- 
nents followed by all available attribute/ value pairs. If a requested type is not available 
at the specified level an empty tag of that type (with a colon) is returned. 

The response unit for an OrmGct request starts with the common response header (i.e. 
OrmVmion:<vmion>) followed by the "OnnGet: <pathname>" line followed by any 
number of the following constructs. 

6.63 Object Entities: 

Syntax : 

<object-item> : = •Object* [*:* <string> *\n* 

<object-link> J *\n* 
<object-link> : : = 'Link* *:* <string> 

Example: 

Object : Network Service Layer\n 
Link: <obj -reference>\n 
Object: Media Access Layer \n 
Link: <obj -reference>\n 

\n (if this is the end of the response!) 

6.6.4 Component Entities: (have no additional properties) 

Syntax: 

<component-item> "Component * [*:' <string>] m \n* 

Example: 

Component : Configuration^ 
'Component : Statis tics\n 

\n (if this is the end of the response!) 

6.6.5 Attribute Entities (simple request) 

Syntax: 

<attribute-item> ::« -Attribute' (*:• <string-> •\n* 

<attribute-value>] *\n* 
<attribute-value> :. :* m Value* *:* <string> 

Example: 

Attribute: Packets sentVn 
Value: 1234\n 

Attribute : Packets received\n 
Value :4321\n 
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6.6.6 Attribute Entities (Info request): 

Syntax: 

<attribute-item> ::= 'Attribute' [•:• <string> *\n* 

<attribute-info> I *\n*i 
<attribute-info> <attribute-value> m \n- <cnt) 

<at tribute-mode> * \n * < cnt ) 
<attribute-ficld> m \n* (cnt) 
( <attribute-range> • \n* I 
[ <attribute-unit> * \n # ] 
<attribute-mode> ::- 'Mode- [ *RO* | 'WO* | *RW # 1 ( *P* I 
<attribute-field>: -Field:' <ORM-f ieldtypo 
<attribute-range>: : = -Range:' <0RM- range -de finition> 
<attribute-unit> "Unit:* <string> 



Example : 

Attribute: Status \n 
Value : Running\n 
Mode : RO\n 
Field: String\n 
Attribute: New Status Vn 
Value : Running \n 
Mode: WO \n 
Type : Enunx\n 

Range : Stopped . Abort ed\n 



Here the sequence of the different info tags is not relevant but "Attribute" always starts a 
new property set for the next attribute. The "Range" and "Unit" tags are optional. 

For "ORM-field type" and "ORM-range-definition" see below. 

Errors & Exceptions specific to this request 

• NoSuchNode: 

The path specified does not point to a legal virtual node/This error is only reported 
immediately after a "Orm{Get/Set/Pam]:<pathname> - ' command. 

• InvalidOperation: 

The path specifies a node, which can not support the requested entity type, an 
"Attribute" request for an "Object" node or vice versa for example. This error is 
reported after a type speafyer, listing the type specifyer (without a colon) followed by 
a newline followed by the error tag. 



6.7 Modification Requests: OnnSet 

The set request starts with the set-tag "OrmSet" followed by a pathname followed by a 
newline. The pathname at minimum must contain the name of the root e.g. "/ <root- 
name>" (i.e. an empty pathname is not allowed!). 
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This line is followed by a sequence of line pairs containing the name of the attribute and 
its value, e.g. 

Syntax: 

<attrxbute-item> ::= 'Attribute* [V- <string> *\n* 

<attribute-value>| *\n* 
<attribute-value> -Value:* <strino;> 

Example: 

Attribute: New Status\n 
Value : Suspended \n 
Attribute: Reset Statistics^ 
Value:Yes\n 

\n (if this is the end of the protocol unit) 

6.7.1 OrmSet Responses: 

If no error occurred, the response to the OrmSet request is a copy of the request itself. 
Otherwise an error-tag may appear somewhere in the response, and if the underlying 
request/response protocol permits, the response is flagged with an error indicator. 

The effect of an erroneous OrmSet sub-request is application dependant but it is recom- 
mended, that a OrmSet sub-request either succeeds completely or has no effects at all 
(atomicity). 

Any OrmSet requests preceding a failed one are not affected, any subsequent requests are 
ignored. 

6.7.2 Error-Returns: 

• NoSuchNode: 

The path specified does not point to a legal virtual node. This error is only reported 
immediately after a *SET:<pathname>" command. 

• NoSuchAttribute: 

The string following an "Attribute:" tag does not identify a legal attribute. The error- 
tag follows the "Attribute:" tag (including the string). 

• ValueOutOfRange 

The value specified is not within the range of legal new values for this attribute. The 
error tag follows the value-tag line. 

• Valuelnconsistent 

The set of attribute values in the request were no consistent or contradictory 

• InvalidOperation: 

The designated Attribute is not writeable. 

• NoPermission: 

The access rights of the requester do not allow to set the designated attribute.fThis 
error and the previous one may have some overlap) 



22 



BNSDOCID: <WO 9802831A1 J_> 



WO 98/02831 



PCT/US97/11885 



6.8 Request Type Independent Errors: 

• ProtocolError: 

[f pairs of tagged lines are expected and the sequence of pairs is not completed or an 
unknown or context illegal tag is detected, this error is generated, following the erro- 
neous tagged line. 

• InternalError: 

An internal error in the application /server was the cause, that this request could not 
be completed, (allocation faUure, mangled structures). This indicates a severe error at 
the server side. 

• BufferTooSmall: 

The response buffer specified is too small to return the full response. 

• NoSpace: 

Some internal buffer could not be allocated or was to small for the requested opera- 
tion. 

6.9 ORM Attribute Info Descriptions: 

Within the ORM protocol there are two ways to retrieve an attribute: the short form 
returns just the name of the attribute and its value and the long form, returning addi- 
tional meta information for every attribute, which can be used to create reasonable user 
interface elements by the ORM client 

The following fields appear n the extended description: 

- Field: identifies the kind of field, this attribute should be presented in 

- Mode: identifies applicable operations (readonly, read/write, writeonly) 

• Flange: Provides hints for input checking and for user interface generation 

- Unit: a free form field often describing the metric of the value or scale. 

6.9.1 ORM Field Types: 

Although in principal the ORM field type item (Field) allows any principal character 
string, the ORM support library and the user interface generator (HTML synthesizer) will 
only support a limited set of predefined field types, to ease the presentation of attributes. 
If a field type is not recognized, the default "String" is assumed. 

6.9.1.1 Field: Integer 

The ORM protocol does not distinguish between unsigned and signed integers, e.g. every 
ascii string representing an integer may be prefixed by a *-* or a There is also no size 
information in the field type. Any range restrictions have to be specified in the Range sec- 
tion. 

Syntax: 
Field:Integer 
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6.9.1-2 Field: Real 

The field type Real identifies decimal floating point values. The allowed input formats are 
those of the POSDC 1003.2 scanf function for float and double values. 

Syntax: 
Field:Real 

6.9.1.3 Field:HexOctet 

This field type is used to display and enter binary data as pairs of hexadecimal character 
Syntax: 

Field:HexOctet (a sequence of hexadecimal digits) 

6.9.1.4 Compound-Field Types: 

The last set of field types allow much finer control of the input an end user may provide 
to the ORM-P client side (or the client of the client...). These types are named Enum and 
Set, where Enum specifies a "one out of m" field and Set specifies a "n out qfm" field. 

Both types are only valid with an appropriate Range field in the hints section, where the 
possible alternatives must appear in a comma separated list 

These two types often transformed into Top-Up" menus (Enum) or option lists (Set) or 
similar by the user intexte^ . 

Syntax: 

Field: Enum (single selection from 'Range:*) 
Field: Set (multiple choices from 'Range:*) 

6.9.2 ORM Attribute Modes: 

To generate reasonable user interfaces (as far as possible without object/component spe- 
cific knowledge), the generator must know, whether an attribute is "read-only", "read- 
write* or "write-only*'* The latter is used to signal to the user interface, that this attribute 
should be only shown in "change-attribute" frames, if those are distinguished from pure 
browsing frames. An extension to these basic modes is provided for writable attributes to 
indicate, that an attribute value is mandatory, by appending the letter "M" 

The different modes are simply encoded as two-letter strings followed by an optional 
T-,e.g. 

Syntax 

- RO Read-Only 

- WO (MI Write -Only (non-null value mandatory 1 

- RW(M] Read- Write (non-null value mandatory) 
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6.9.3 Range Identifiers: 

The range identifier, tagged with "Range- is used as a kind of hint (and therefore it is 
optional except for the compound fields) to the user interface generator; what kind of 
input/output field it should generate. In addition the information can be used to check 
any optional input and give the end-user appropriate responses or hints, tf these input 
checks fail. 

The ranee hints are type specific and as such different conventions are defined to specify 
valid ranges for an input field. The type independent convention* to separate aiterna. 
tives by a comma and sequences by three subsequent dots ... 

6.9.3.1 Range Specifications for Integer Fields: 

Valid range specifications for the integer types are: 

Range:!. 4. 8. 16 valid: 1 of the values li»*ed 

Ranoe-20 60 valid: all numbers between 20 and 60 including 

Range *0 *** valid: every integer including 0 (up to typemax) 

Range' -20 +20 valid: every integer between -20 and +20 incl. 
Ran g e ! valid: every pos/neg integer within type 

6.9.3.2 Range Specifications fro Floating Point Fields: 

Valid range specifications for the real types are: 

Range -0 1 0 5,0.8 valid: one of the values listed 

Rangeio!le-3. . .0.1 valid: reals between 0.0001 and- 0 . 1 



6.93 3 Range Specifications for String Fields 

If the first range value starts with a digit, the range indicates either the maximum or the^ 
range of valid string lengths. If the first character is non numeric the range is interpreted 
similar to the compound Enum field below, Le. one of these strings may be selected, but a 
different user interface element may be used (a list box). If the first character of the range 
string is a comma V, this provided strings in the comma separated list are treated as 
examples, where the possible input is not restricted to the given alternatives. A major use 
of this kind of string selection is in file selection boxes. 
Syntax: 

Range:!... 20 valid: strings with minimum length of 1 

and max length of 20 characters 
R^nye-iO valid: a string with at max 20 characters. 

Range : , f i lei. c,£ile2.c filel.c or £ile2.c are valid options. but 

other input is also valid 
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6.9.3.4 Range Specification for Compound Fields: 

For the Enum and the Set type fields lists of alternatives are required in the range section. 
The comma separated list identifies the different options a user is allowed to select. 

Syntax: 

Range :<comma separated list of alternatives> 
Example: 

For Enum (choose one of) 
Range : STOP , SUSPEND , ABORT 

For field type Set (choose n or none of) 
Range: Trace IP, Trace UDP, Trace TCP 



6.9.4 The Unit Specification: 

The "Unit" specification is a free form string and currently not interpreted by the user 
interface generator. If present, it will append this string behind the value field as one 
would do with a unit description like "1.4 inches'*. Another important purpose of this 
field is for the use with customized object specific management pages (if used within an 
HTML environment). Here the unit could be used to identify an application specific type 
for example. 

6.10 Navigation Request: Path 

This request extends the previous operation (OrmGet or OrmSet) to a new subtree and fol- 
lows these tags in its syntax. It may appear everywhere, where a OrmGet or OrmSct tag 
may appear, except that it must be preceded by one of these items in the same protocol 
unit It usually is only found in sequences of ORM statements resulting from a "Dump" 
request! 

Syntax: 

OrmPatfc: <parhnamp> 

Semantics: Extends the previous OrmGet or a OrmSct request into another subtree within 
the same object 

6.11 Summary of ORM Error Codes: 

NJoPermission: 1 

The current authentication can not be used to perform the requested operation 



NoSuchNode: 2 

The pathname specified in a Orm[Get/Set/Path] request does not point to a known 
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node. 

NoSuchAttribute: 3 

The attribute specified in a OrmSet request could not be found 

NoSuchObject: 4 

The Object specified could not be found. 

InvalidOperation: 5 

The operation requested is not valid for this type of entity. (Example: attribute is not 
writable, request components of an attribute) 

ProtocolFailure: 6 

A sequence of tags was encountered, which could not be parsed and decoded. 

VersionMissmatch: 7 

The object could not deal with the version of the request packet. 

CommunicabonError: 8 

This is a client side error to map lower level communication errors too. if necessary. 

ValueOutOfRange: 9 

The value passed in with a set request for an attribute is not within the allowed range 
and could not be accepted. 

Valuelnconsistent 10 

The combination of values passed with a set request is not acceptable. 

NoSpace: 12 

The request could not be completed because of internal space restrictions in the object. 
BufferTooSmall: 13 

The response to the request exceeds the size of the response buffer provided by the 
underlying protocol. 

Internal Error 14 
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ApplicationError 15 

These two errors are used to report back implementation problems like corrupt data 
structures, where the IntemalError usually is generated by the ORM support library, 
the ApplicationError instead is issued by the higher "application" layers. 
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3-1 ORM Protocol Layer And Upcall Interfaces 

This section was generated from <sUin> by CDOC on Sun Jan 29 17:00:50 1995. 
ORM Application Context 

Application Server Capsules may >erve different kind of requests and therefor may have 
multiple domains of objects to he managed listening on multiple ports. Following the 
ORM model, this may result in multiple parallel independant trees. 

The ORM parser supports this by maintaining an application context, which has to be 
passed to the protocol layer to handle a request (there is also an opaque call-context, 
which may be passed to the protocol layer, but this isn't interpreted by the ssl). 

The application context contains beside (an opaque pointer) to the (virtual) root of the 
virtual tree, mainly a list of tree/application specific function pointers. Before the first 
request can be passed on to the ORM protocol layer, this context has to be established 
with the ORM SSL via a call to ORM.Contextlnitialize. 

Accordingly there exists a function to inform ORM that this application context is not 
needed anymore (release). 

The following lists the function prototype definitions for actual functions to be provided, 
when establishing a context. 

Note: Some functions are defined to return pointers to character strings (ORM.String). If 
the ORM protocol handler is used it is guaranteed, that the same function will not be 
called, before the string is copied or otherwise not needed anymore. This allows the use 
of a single private string buffers per function, if necessary. 

3.1.1 Authentication 

The following list of functions are included to enable an application to maintain its own 
authenticated context. The ORM protocol just allows to forward some authentication 
related information from the client to the server (WHO...). This is passed on to the appli- 
cation layer as is, if encountered by the parser. The actual meaning of this data is applica- 
tion and user interface dependant. 

3.1.2 Function Type ORM.AuthenticateFunc 

Performs any necessary authentication or preparation of authentication structures. Usu- 
ally, the authentication information is used to setup some context in the call-context, 
which is passed to the node/handle layer upcalls. It is up to the application layer to 
free/clear such context after return from the protocol layer. 
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Declaration: 

-»XM_AppC3 1 : --r.tex.tDef callc:n:ext , / ° in • / 
- ?v>1 _- r r 1 aucfcstcing /* m •/ 



Fields 

callcontcxt 

authsthng 
status 



An opaque pointer to any kind of context, the caller has estab- 
lished.This passed to the node and handle layer. 

The string, the client passed in his request if any. Usually 
uid.passwd 

ORM_E\ ; oError: if successful!, ORM.EPermissionDenied, if 
authentication unknown. 



3.1.3 ORM.AuthFuncDef 

This structure is used to pass the Authentication function to ORMjZontextlnitialize 
Declaration 



r'pe i€ 5 ::r'.:; hx. a j z h F - r. * 
- ?X _ A j :: r.«?r.i i race Tunc 
1 A.-r..-::ef; 



Tag I 



3.1.4 Virtual Node & Tree Function Types 

The following hst oi functions (function types) are used to access the virtual tree of com- 
ponents, attributes and linked objects. They usually don't deal with application specific 



3.1.5 Function Type ORMJSfodeLookUpFunc 
This is the central function for the traversal of the tree 



Returns an 
retriev- 



es an opaque pointer to a virtual node, which may subsequently be called to 
>e properties or children of specific tvpes. 



pec i tic types. 
Declaration: 

t -/pedes ;?>! ...Scavja ('CRM ModeLookUpFunc ) ( 



:P.H^App:Ai;CenccxtDe: 


:allccn:ext, 




in ■ / 




root. 


/ a 


in «/ 




pa tr.r.«ame , 


/ • 


in ° / 




•node. 




out ° / 




°nd_type 


/* 


out »/ 



Fields 
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callcontext 



root 



pathname 



node 

ndjypc 

return 



is an opaque pointer to the application specific call context pro- 
vided with the Do.Request function. 

Opaque Pointer to root of virtual tree. This may be NTULL and is 
taken from the application context. 

is a / separated list of component names optionally preceded by 
the name of the object (e.g. if the first component matches the roots 
object name, strip it, else take the first component to be a child 
under the applications root). Support for un*x style directory navi- 
gation . and .. is highly recommended/ required. A pathname of .. 
applied to the root with request type Object should return the root 
name and the actual servers link address (NOR) 

The opaque node pointer, if found 

The ORM_\'odeType of the node found 

ORM.EX'oError in case of success, or any other ORM error in case 
of failure. 



3.1.6 Function Type ORM.NodeChildNextFunc 

Used to subsequently scan the children of a single parent. Returns the next child of type 
type of parent pix rent, "which logically follows the child returned by the previous call to 
NodeOuldNextO. now passed in as lastchild. E.g. If tastchild is set to NULL the logically first 
child of this parent is requested. If there are no children (of the requested type), then 
NULL must be returned with ORM.Status set to ORM.NoError. 



Declaration: 

type-ief c;<M_5 1 ^ i < •Cr^N-'ieChildN'ext func 

C?_M_AcpC* 1 .rrncext.De: rail context, / * 

CRM AppN^cieOe i rent / /* 

CKM^.ppHcrieDei i as -.child, /• 

•;PM_N?2eTyce:e: -ype, 

:p:-t_AppN > ict-e c • ;hiici, 

J : 



) ( 
in • / 
in • / " 
in • / 
in • / 
out • / 

OJC V' 



Fields: 

callcontext 

parent 
tastchild 

ty th- 



is an opaque pointer to the application specific call context pro- 
vided with the Do.Request function. 

Opaque pointer to the virtual parent node. 

Opaque pointer to the last child returned by a call to this function 
(in this request), or MULL to request the first child. 

The tvpe of entity, which is requested (ORM_ObjectType, 
ORM.ComponentType, ORM.AttributeType or ORM.AnyType). 
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node Pointer where to store the reference to the node found 

mme Pointer to name of node found. 

reiur ™ status value. Possible status values, see below! 

3.1.7 Function Type ORMJModeChildByNameFunc 

The little sister of ORM.Nodtf LookUp. Looks for a child with name childname directlv 
under the given parent parent Th.s function is primarily used within the pw«K 

" there 15 n ° ChlId ihlS ™ ura WLL a ^^nSr sta- 

Declaration: 

typedef CR.HJca:u; < *OR.M_\'cceChildByNa:neFunc ) ( 

" P-M^AppCa i 1 ■; I e :< <= f Cillccntext, / ° in • / 
wr.M_Acr.;:-cicOef parent, /* in «, 
_ cn;idnam*, / * i.-, « / 

"M_;,:a;S v Z ... ref -child, /• out •/ 

-r^_r;.. c ryz-r-r: °:niij_:ype /« cut v 

Fields. 

f* 1 ™ 1 ' Opaque pointer to the virtual parent node. 

childname Name of the child (attribute), i.e. every printable char except 7 ' 

chiU Pointer where to store the reference to the node found 

chiMjvfh' Pointer to type of node found. 

return ORM.EXoError if child was found, else ORM.ENoSuchNode. 

3.1.S Function Type ORM.NodeTypeGeeFunc 
returns the type (enum ORM.N'odeTypeDef) of the given node. 
Declaration: 



typedef CRM N-^ T ype3«f t 'CRM.KcdeTypeGetfur.c 



Fields 



'1 pointer to a virtual node 



returns 



a valid type orORMJSJodeTypeUnknown. 
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3.1.9 Function Type ORM.NodeNameCetFunc 
returns the name (ORM.String) of the given node. 
Declaration: 

-.ypcief ;:-M_3r r : rq ( «-?P>!_N'--icNamc*GctFunc ) < 

) ; 

Fields: 
node 
ret urns 



a pointer to a virtual node 

a valid null terminated string of characters or NULL 



3.1.10 Function Type ORM.NodeNotFoundTrapFunc 

This function is kind of special by providing the application layer a chance, if the lookup 
of a node failed, to create that node. 

Normally, referencing a non-existent node in the pathname of an ORM request is treated^ 
as an error, except this is an internal ORM restore request. Reloading an ORM tree into an 
application may encounter subtrees, which where dynamically created by the application 
during a previous run (usually via a te subtree). 

This function is totally application dependant and is not covered by the ORM-SSL other 
than via this hook. 

Declaration: 



ivjs I'Cr.X ScseSc-.Fcur.dTraptunc) 



irc !.^: :> ::fiu»Ji : e - - -r s : , /■ in 9 f 



Fields: 
parent 
name 

new n otic 
return* 



Reference to parent node 

Name of node not found under this parent. 

Kind of ORM request (get /set/dump/restore) causing this lookup 
failure. 

Where to store the reference to the new node, if one was created. 

ORM_ENoError, if a node with the given name was created else 
ORMlENoSuchNode. 
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3.1.11 Structure ORM.NodeFuncDef 

This structure bundles the virtual tree related functions for passing to Contextlnitialize 

Note: TheORM.NodeNotFoundTrapFunc is not included in this function array, because 
it is application special anyway and must be passed explicitly, see ContextlnitiahseO 

Declaration: 

typ^der struct C?^__NcdeF jnct^g I 

CFuM^^eLcor.UpFunc lookup; 

P.M_N r ziQ'Z - i 1 jiNe.N c F - r. z childnext; 

.:.=iM - .\ , ^ue". w . i l^fcyNdrr -»? ch ; idryr. A.T.e ; 

-•^_*-'w -<??ype:«et F-n- typeset; 



3.1.12 Application Handles 

The following two function types are used to link the virtual nodes in the tree to (pans of) 
actual application data instances, visible to the ORM support layer as opaque handles 
When an application handle is requested from the application layer, real things happen to 
start and it is assumed, that the instances are valid and available, until explicitly released" 
by the ORM layer The handles together with the aspect (identifying the type of handle to 
the application) will be passed to the application specific functions, when actual values 

vf, V 'f !° b 1; 1C ' " eSSrv1 Ceit her foryt '' or * 11 U these fc»™«ns are not set in the ORM context 
.NULL will be passed into those calls for both, the handle and the handteclass. 

3.1.13 Function Type ORM_HandIeGetFamc 

Request (and lock) an actual handle (pointer to an application level instance) and a han- 
dleclass based on the current virtual node and the current principal. 

Declaration: 



> ; 

Fields: 

CiiHcontsxt 



Z'ry v. r r : ; •_ . — ; , e : "ce, .■ • ^- o# 

TypeDe! op, /* i n □/ 

:^_Apchar.?.:<s;ef "handle, /• out •/ 

CFLM pAscesiS-fc!: 'aspect /° out 9 1 



is an opaque pointer to the application specific call context pro- 
\ ided with the Do.Request function. 



f,|,| ' r Pointer to current Node. 

°P Operation Code, e.g. ORM.Request 

handle Pointer, where to store the handle reference 
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aspect Pointer, where to store the aspect reference 

returns ORM.ENoError if no error occured or any of the ORM error codes. 

3.1.14 Function Type ORM.HandleReleaseFunc 

Returns a given handle back to the application layer. This should be more understood as 
an unlock operation than a free! 

Declaration: 

Lypede f v;:J ( • O °. V _H 2 n il e Rc 1 e a 3€ r unc ) ( 

CP>i_AppC£::Conie\'cDef callccncext , /• in ■/ 
CP.M_AppKar.iie^ef handle, /* in «/ 

1*H_v AopA3rec::ef aspect, * " ' 

- zy d ._ j _ j. c • 7 /i-Cf! L • • P 

) : 

Fields. 

t-*j//tiV»/('.Vl 



is an opaque pointer to the application specific call context pro- 
vided with the Do.Request function. 



handle * handle obtained via a call to HandleGet 

aspect Aspect as returned from HandleGet 

op Operation Code, e.g. ORM.Request 

3.1.15 Function Type ORM.ObjectLinkGetFunc 

Retrieve the Object Link from a node of type Object given the node, the handle and the 
aspect. The standard Handle Layer functions just return the link stored in the corre- 
sponding field in the node struct. 

Declaration: 

typedef CTV- iti: j3 '. •OPM_Har.dleC-fciectl.ir.ScGetFunc ) < 
?R.y A:::;N ? 1~re? r.uie, /• ir. */ 

CX^T Acp:-ancl*3*f -*r..ile. /• ir. •/ 

• y".*. r t .* * ::• * * **-• ' + * C*SC t . / • I n • 

. ■ . . - * - -r.K / • Cut • / 

Fields: 

node Reference to node of Object Type 

handle Reference to application defined handle as returned from Han- 
dleGet 

aspect* Reference to application defined aspect as returned from Han- 
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link Location where to store the reference to the sthngified link infor- 

mation 

returns ORM_E\'oError if successfull, else ORMJnvaUdOperation, if the 

node is not or type Object 

3.1.16 Function Type ORM.AttributeDescrGefcFunc 

Retrieve the opaque reference unique to a node of type Attribute (usually the attribute 
descriptor), given the node, the handle and the aspect. The standard Handle Layer func- 
tions just return the pointer stored in the corresponding field in the node struct. 

Declaration: 

cy:;cJ-?r .*. 5 * i z .. : : ' ~ r :*' r.-i*. vAt t ri b?JceDescrG*t:unc ) ( 

- 1 >' * c - • : -;■» ~ -■ - : ct U i «? , /"in*/ 

:?^_A^cA-ic::.:e: ±spect, / * in •/ 

** _A A * - . u e j c- r * 2 r ^ r i bde sc /' our. v 

Fields: 

node Reference to node of Object Type 

handle Reference to application defined handle as returned from Han- 

dleCet 

Reference to application defined aspect as returned from Han- 
dleCet 

attribdesc Location where to store the reference to the attribute information 

returns ORM.ENoError if successfull else ORMJnvalidOperation, if the 

node is not of type Object 

3.1.17 Structure ORM.HandleFuncDef 

This structure bundles the handle related functions for passing to Contextlnitialize 
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Dec la ration: 

:p.m :-:ir.^l-=3^i r ur.c get; 
■;R»"-!iir.aIePelcastfF':r.c rosle&sc; 
0Rm". j .4 nd: eOb ;ec:l: r.< 0* - Tunc Iir:< ; 

CR>! :-;ir.C.'.eA:tribv.tcOerc:G€tr-jnc attnfr; 
) crvM_H& r.n-eFuncDe t ; 

3.1-18 Accessing Application Data: Aspects 

the following group of functions (function types) has to be provided to access actual val- 
ues of the application either for retrieval or for updating. All functions in this group are 
mandatory, if the ORM protocol layer is used. 

3.1.19 Function Type ORM.AspectCallGetFunc 

This function retrieves an aspect from the application layer, e.g. a reference to a blob of 
native application data (a pointer to a (part of) an application data structure, or a 
response buffer >. The ORM protocol layer calls this function once for every unique 
handle/aspect combination (and not per Attribute) within a single AttributeCet Request., 
[f the HandleCet Function returns a different pair or there are no more attribute nodes to 
process, the current aspect is released! 

Declaration: 

'•:P^_ApcK^ n - ,c»- e i -anal*. /• in ■/ 

-Hy. .^pAir^r t ;e: aspect, /■ in •/ 

CJoO-xc—caPr s-ra: *-urren- /« out */ 

) : 

Fields: 

handle Handle as retrieved from HandleCet 

aspect Aspect Reference, as retrieved from HandleCet 

current Where to store the reference to the current value (opaque) 

3.1.20 Function Type ORM.AspectCalilnitFunc 

This function requests an aspect container from the application layer, e.g. a reference to a 
blob, where new attribute values can be selectivly written to to perform AttnbuteSet 
requests In addition hte application laver may return a reference to the current aspects 
values (cmp CallCet). which is passed unchanged to the CallSet routine. The ORM proto- 
col layer calls this function once for every unique handle/aspect combination (and not 
per Attribute) within a single AttributeSet Request. If the HandleCet Function returns a 
different pair for a node or there are no more attribute nodes to process, the CallSet ^func- 
tion is called (Note: AspectRelease is only called for aspects retrieved via CallCet!) The 
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ORM SSL implementation of these functions copies the current values and returns a ref- 
erence to this copy in new and a reference to the current values in current. 

Declaration: 



t".*'. A^iCiiartrr^f "new, /• out • / 

v.;:;:. at 1?- r~,ef 'c-rron; /■ cut •/ 

) ; 



Fields: 

handle Handle as retrieved from HandleCet 

rts/nv/ Aspect Reference, as retrieved from HandleCet 

«i-;r Where to store the reference to the native blob to update with new 

attribute values (opaque) 

current Where to store the reference to the current aspect (opaque) 



3.1.21 Function Type ORM.AspectCallSetFunc 

This function is called to actually apply the new attribute values for the current aspect by 
the application layer. It is up to the aspect/application layer to check the values in the 
request structure for validity and consistency and to determine which attributes got new 
values (by comparison with the current values). In addition it is the responsibility of the 
aspect/application layer to deallocate any structures allocated by AspectCalllnit. Only if 
the Set-Function is not called, the call to AspectRelease is performed. 

The ORM protocol layer calls Set-function once for every unique handle/aspect combina- 
tion (and not per Attribute) within a single AttributeSet Request. If the HandleCet Func- 
tion returns a different pair for a node or there are no more attribute nodes to process, the 
CallSet function is called (Note: AspectRelease is only called for aspects retrieved via 
CallCet!) The ORM SSL Implementation of these functions copies the current values and 
returns a reference to this copy in new and a reference to the current values in current. 

Declaration: 



typed!?: f 5 r i:.is i* "•?:^Aioec:C« 1 1 Setfuno ( 

Cr.MjVcpAspecr."-:: a*c>*ct, /* in •/ 

CPy._ApcD&t a?t cDef r.ew, / • in •/ 

■;3M_A::p&<8 r . i? t rC/cf current , / ■ in * / 

cr^M_5t r;no • isJetail / • out • / 
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affect 

current 
rsdetail 
returns 



Aspect Reference, as retrieved from HandleGet 

Where to store the reference to the native blob to update with new 
attribute values (opaque) 

Where to store the reference to the current aspect (opaque) 

Where to store a textual hint, why the call failed, if any. 

ORVLEN'oError if new values could be applied successfully, else 
ORM.ERange. 



3.1.22 Function Type ORM.AspectReleaseFunc 

Used to tell the application laver. that the reference retrieved via an AspectCet or Aspec- 
Unit call is no longer needed anvmore by the ORM layer. This function is called, when 
CetHandle returns a new handle aspect call within a AttributeGet processing or a conver- 
sion in an AttributeSet processing failed. 

Declaration: 



..:rr»*r:: 4 * -n * / 



) ; 

Fields: 
handle 

current 
reqtype 



Handle as retrieved from HandleGet 

Aspect Reference, as retrieved from HandleGet 

Reference to data as returned from AspectCalllnit or Aspect- 
CallCei 

ORM.RequestCet or ORM.RequestSet depending whether this 
datapTr resulted from an AspectGet or Aspectlnit call. 



3.1.23 ORM.AspectFuncDef 

This function groups the function pointers of the aspect layer 
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Declaration: 



•:P.V_A3pect.Cj Jet Fur. r raliget ; 

T A s ;;u : 1 C - a J. 1 1 r. : * F :: c rallinit 

CaM^Asp^ctCailSetFcr.c callset; 

CRM_:\.r nc-cc Rei oa sef-:: ? re 1 ease ; 



3.1.24 Attribute Functions 

The following group of functions is called to actually perform the the single attribute 
Get/Set and the corresponding conversions between the applications native and the 
ORM (ascii) presentation. 

3.1.25 Data Structure: ORM.AttributelnfoDef 

This structure is used to return the all the meta information and the actual value of an 
attribute, it is passed by reference to the application/attribute layer to be filled. Note: The 
string pointers do not point to valid buffers, when passed to the attribute layer! 



."TAl ; 22 i 6< ) , STRING, HZXCCT. 




i~3 ascii 



presentation 



. ::u :<i";e string 
7: .-r -r.:; string 



Declaration: 




s :. c 



-::-ieIn£cTag i 





3.1.26 Function Type ORM.AttributeNativeToSfcrastgFimc 

This function converts the applications native value of an attribute, specified by handle, 
aspect and the attribute descriptor to a C-string (ORM.String). 
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Declaration: 



typede i CM m 


5*. i-us CCPM_A 








AppAspeciT e t 




AppAt r.ricCcSw-r 




~A=pDataPt rSe: 







nandle, 
aspect, 
ate cib^escr, 
datapt r, 
'st rvai-e 



/• m •/ 

/ » in ■/ 

/• in •/ 

/* in •/ 

/ • out • / 



Fields: 
handle 
aspect 
attnluirscr 
Jataptr 
st rvalue 
returns 



Handle as obtained from the last call to HandleCet or NULL. 

Aspect as returned from the last call to HandleCet or NULL 

Attribute Descriptor as returned form AttribDescrCet call. 

Opaque Pointer as returned from AspectCetCall. 

Where to store the reference to the converted value. 

ORM.ENoError (Null) if conversion was successful^ else a valid 
ORM Error return code. 



3.1.27 Function Type ORM.AttributeNativeToInfo 

This function performs the same as the previous function ORM.AttnbuteNativeToStnng 
except that a also provides the additional meta information to this attribute, as far as availa- 
ble. 

Declaration: 



-ypedef CMjiavii i^cSM.Af.ributieNAtiveTcrnfcFuncl ( 
C*KM_AppHan di«~e f nandle. / * in ■/ 

r.^j- AteA.softctCii aspect , /• ^ " 

:i5> r Ar pA.::r:M'*scrDef fit t r ibaesc r . / • in ■/ 
- ~ ... _.\ ".-...* ... - - r • r 7 : lAt ipt. t ( •** in ■/ 

;'<*~htz i:ci;;%;r.f into " in* i 



r.di rect out • / 



Fields: 
handle 
aspect 
attribde>cr 
dtUriptr 
ext re] 



Handle as obtained from the last call to HandleCet or NULL. 
Aspect as returned from the last call to HandleCet or NULL 
Attribute Descriptor as returned form AttribDescrCet call 
Opaque Pointer as returned from AspectCetCall. 
Pointer to structure, where to store the string references. 
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return, ORM E.NoError (Null) if conversion was successful!, else a valid 

ORM Error return code. Ud 

3.1.28 Function Type ORM.AttributeStringToNativcFunc 

This function converts an ORM.Stnng value for an attribute into the applications ™ 

Declaration: 

v/pcdcf :a.Vta:u* . '-C^A: ribut ri ngToNat i veFunc) < 
:.^_Apcr-.ir.-.^r^; r.ar.dle, /■ in ... 

-r.v_Arp/-.sfJcci^-:-f Aspects /* i n »/ 

. ■:• .a;c.v. : :^ at c ritxiesc r, - ir , • / 
•^X^'-I ^tapir, in# indirect cue •/ 

Fields. 

handle Handle as obtained from the last call to HandleCet or NULL. 

aspect As P* fCt * s ^turned from the last call to HandleCet or NULL 

MtnbJescr All nlu.w Descriptor as returned form AttrtbDescrCet call. 

dataptr Opaque Pointer as returned from AspectGetCall. 

it rvalue \ e w value as a C-String (ascii). 

npi!- c E ' N ' OErrf,r <NUU> " conversi °" successful., else a valid 

ORM Error return code. 

3.1.29 Structure ORM.AUributeFuncDef 

This structure bundles the attribute related functions for passing to Conteatlnitialize 
Declaration: 



cypedet JU-.ct :?.V_Attr::.: e fjncTag i 

Q £Z-* f : l SibU = e£ * r 1 ns ' r > N 1 - ^«P'«C st riagtonative; 



:RM - Act r,r * • t.T..::..f )Fu r.c inf ctssiring • 

3.1.30 Structure ORM_ContextDef 

This is an internal structure to ORM and opaque to the application layer It stores the 
funct.on pointers and the information of the root node. PP " CaU ° n ,ayer 11 stores tne 

•Note: This structure and the related' procedure definitions may change 
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authfuncs Pointer to list of authentication related functions or NULL, if no 

application specific authentication is needed. 

notfound No description 

3.1.32 ORM_ContextRelease 

Release .in Application Contevt 
Prototype: 

vol 'J 

CRM Ccn:e>: t>'.*lea. ? e'( CP>!_C:r.;e.\:Sef conczt) ; 
Parameters: 

contxt Pointer to application context as obtained from 

ORM.Contextlnitialize 

3.1.33 ORM.DoRequest 

This function calls the protocol layer to parse an ORM request received and act on it 
accordingly via upcalls to functions in the application context, i.e. this is the function to 
be dispatched, when ORM requests are received on a server port. 

Prototype: 



L 



'rnaxresp 



Parameters: 
n^ijict.rf 

reqlen 
rc>t*Gn$c 



The application context reference as returned from 
ORM_Contextlnitialize. 

An arbitrary call context (reference) maintained by the application 
layer and passed to the authentication, node and handle upcalls. 

Pointer to received ORM request 

Length of request buffer in bytes 

Pointer to allocated response buffer 
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maxresp Reference to maximum response buffer length in bytes, on return 

points to number of bytes used in response buffer 
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3.2 ORM Node Layer 

This section was generated from <stdin> by'CDOC on Fri Jan 27 19:59:34 1995. 

The ORM Node layer adds another level of ORM application/server support, as it actu- 
ally maintains a tree structure to access the application level datastructures. 

This level is accessed from the application/server level via the ORM_Node... functions to 
actually build /destroy the tree of objects, components and attributes. 

On the other side it is called from the protocol level and frees up the application to pro- 
vide the appropriate functions for navigation and name space/entity management itself. 

3.2.1 Application Handles 

The nodes of the node layer provide a tree structured view to application/ server level 
data, but tlwv vusuallvKlo not contain the actual data. A link to the actual instances of 
application lev ei data is maintained by handles and aspects. Both are opaque to the ORM- 
IVode level but are interpreted at the layer on top of ORM-Node. Typically the handle is a" 
pointer to some application level instance, and the aspect is a pointer, index or type iden- 
tifier, which identities the type of the instance 

3.2.2 The ORM. Node Structure 

Instances of this structure maintain the tree of virtual components, objects and attributes 

Every node has a name and a type, identifying the three different entity types: Object 
Component or Attribute. Object and Attribute nodes are leaf nodes, e.g. they can't have 
children 

In addition, every node has a parent and a next pointer, to link the actual tree structure. 
Only component nodes have a pointer to the list of children. 

Object Nodes have an additional attribute, called the Link (or Link-Info which usually is 
a stringified NOR). 

Attribute Nodes reference a single attribute by, which is characterize by additional infor- 
mation like 

• a value type, which describes the kind of value e.g. integer (different sizes), real 
(sizes!), string, stti$le-sclectton or multiple choice 

• a value mode, specifying this attribute as read-only read-write, write-only or persist- 
ant. 

• hints section, which contains additional information for use by the user-interface crea- 
tor e g. valid ranges for this value and a unit string. Both values are optional. 

The nodes provide a tree structured view to application/ server level data, but they (usu- 
ally) do not contain the actual data. 
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3.2.3 Struct NodeDef 

Declaration. 



char 

struci CRM_N;>deTag 

j n i j n 



: y ce ; 
r lac; 
r na.T.e; 
'carenc; 
•r.ex:; 
handle; 



, *: i 7 j j •first; 
-T.V: M-cTia •last.; 



1 a-trib; 

:cc I 



Fields 

fl*S 
name 

parent 

next 

handle 

aspect 

u.comp 

u. camp, fir $t 

n. com p. last 

uattrib 

u.attrib.descr 



indentiiies the type of entity, this node describes, i.e. 
ORM.ModeTypelObject, Component Attribute, Unknown] 

Internal use 

The name of the node (object component or attribute name 

pointer to the parent in the tree, NUL for the root of the tree. 

pointer to next sibbling in chain. This defines the order in which 
nodes of a given type appear in the response 

an opaque pointer for use by the upper layers 

another opaque identifier for use by the upper layers 

union variant for component nodes 

pointer to first child of this component node 

pqintecto last child of this component node* < 

union variant for attribute nodes 

opaque pointer for use by upper layers 
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u.obiectAmk pointer to stringified link-address of this object (NOR), e.g. the 

hyperlink 

3.2.4 ORM_NodeCreate 

Creates a new unlinked node. Usually only used by convenience functions and to create 
the root node- 
Prototype: 

C~.M_N ;:e*e[ 

q-.^n - -c-: roar ■= ( ZK>\_S r . r v :.q name, / * in */ 

:?M_Nc-e Typer-er type /* in */ 

Parameters: 

name The name of this node (for navigation) 

t y pi . The type of this node. This type also determines which functions - 

can be applied to this node later on. 

3.2.5 ORM.NodeDelete 

Deletes the given node and all its children e.g. returns the space allocated Note: if the 
nodes parent pointer is not NULL the node will not be deleted. 

Prototype: 

x r.t 

Parameters 

node The node (and the subtree) to delete 

3.2.6 ORM.NodeAttach 

Attaches a node (and its subtree) into an existing tree as a new subtree. Every node (sub- 
tree) is in at most 1 tree! 

Prototype: 

CPM Nr ?'Ac : a:r t :r>i He.£::or.Der relation, /• in */ 

:P.y_Ncr*RDef relative, /• in •/ 

NcceOet* subtree /■ in */ 



Parameters: 
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relation : Rag either ORM.NodeSibbiing or ORM.NodeChlld, specifying 

the role of the relative node, e.g. its a sibbling or its the parent of the 
subtree to attach. If its a parent, the new node will be attached at 
the end of all children, if its a sibbling, it will be placed right before 
this child. 

rclittiv? : an existing node, either parent of sibbling 

iuhlrte Mo description 

3.2.7 ORMJModeDetach 

Detaches a subtree from the current root tree. This i .vays has to be called, before a sub- 
tree is actually deallocated. The subtree may also be reattached in the same tree again 
after this call 

Prototype: 

No parameter descriptions are available. 

3.2.8 ORM.NodeHandleSet 

Sets the handle in the given node (see also ORM_Node<convenience functions*) 
Prototype: 

OI04_AcpH.an:ileDcf handle 

Parameters 

node Reference to node structure of any type. 

handle Reference to opaque handle. 

3.2.9 ORM.NodeHandlcGet 
Retrieves the handle from a given node 
Prototype: 

OPM Ar-pHandieDet "handle / ° out ° / 

* . 

No parameter descriptions are available. 
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3.2.10 ORM.NodeAspectSet 

Sets .he aspect m .he K .v«n node (see also ORM_Node<convenience functions*) 

Prototype: 

vci;i o---n»f node, /" *' 

~ CRM_AcpAs?ectDef aspect / in / 

) ; 

Parameters: 

„^ Reference to node structure of any valid node type. 

, JS;Vt Reference to opaque aspect description. 

3.2.11 ORM.NodeAspectCet 
Retneves the aspect from a given node 
Prototype: 



= ' \ :uen.?f rede, 
v :-iA.*cec-Ce£ -aspect 



No parameter descriptions are available. 
3.2.12 ORM.NodeAttributeDescrSct 
Sets the attribute description of an attribute node 
Prototype: 



/ ■ 



> ; 



: HX AppAttribCescrr-ef attrifc 



Parameters: 

nodr Reference to node structure of type Attribute. 

attnb Reference to opaque attribute description 

3.2.13 ORM.NodeAttributeDescrGet 

Gets the attribute description of an attribute node 
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Prototype: 

C w A 1 1 r i ou : e:-e i : rGe : ( ORM_NodeDef ncde, /• i n • 

:?M_AppAtt ribDescrDef -aitrib /• out • 

) ; 

No pan meter descriptions are available. 

3.2.14 ORM.NodeObjectLinkSet 
Sets the link of an object node 
Prototype: 

Parameters: 

"ode Reference to node structure of type Object. 

link Stnngiiied version of the address/nor to call this object. 

3.2.15 ORM.NodeObjectLinkGet 

Gets the linkaddress of an object node 
Prototype: 

r\z*e t /• in •/ 

No parameter descriptions are available. 

3.2.16 ORM.NodeObjcctAdd 

for an explanations or paramters, see above. Return created node if operation succeeded 
else NULL. 



/ • in v 
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Prototype: 

^-n!^,^A^( CK.M_Relatior.Def region, /• in ., 

w - -om Ki^^nef relative. /• in •/ 



CRM_N~deQef 
;FM_string 
CRM AppKandleDef 

CKM~AppAspectSef aspect. /• in •/ 



name, /"in • / 

nandle , /• in •/ 



;f^M String 



linicadcr /• in •/ 



No parameter descriptions are available. 
3.2.17 ORM.NodeComponentAdd 

Prototype: 



CRM NcaeCcnpor.er.tAid I 



No parameter descriptions are available. 
3.2.18 ORM.NodeAUributeAdd 
Prototype: 



CRM RelationDef relation, 

C KM^N- -aeDc f relative, 

0 PM~ 3 tcir.g name, 

?:-M_AppKandleDcf handle, 

C^M^AcpAspectCef aspect 



/• 


in 




/ 


/ • 


in 


• 


/ 


/• 


in 


• 


/ 


/ « 


in 


• 


r 


/• 


in 







name. 



7PM_AppKar.il eSe f 
~KM AppAspectDef aspect, 
ORM_AppAttritoDesccDef attribdescr 

) ; 



No parameter descriptions are available. 



/ • in 
/ • in 
/ * in 



nandle, /* in •/ 

/ • in - / 
/* in */ 
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3.3 ORM Aspect Layer 

This section was generated from <stdin> byCDOC on Sun Jan 29 17:00:51 1995. 

The ORM aspect layer adds another level of ORM application/ server support on top of 
the OR.VI \ode/ Handle layer, and supports the retrieval and modification of aspects, i.e. 
groups of nttnbutesfrom or into application data structures, once those have been regis- 
tered with this layer. 

This level has no additional (down-call) functions but defines data structures to be pro- 
vided by the application layer. These are then accessed/used by the aspect upcail func- 
tions, if those have been registered with the ORM protocol Layer. 

The Aspect layer implementation of the ORM-SSL works as follows: 

On AspectCallCet requests, just a pointer is returned which points at offset bytes (as set 
in the aspect descriptor) from the beginning of the handle. On AspectCalllnit calls, a copy 
of the aspect. e.j» >tze bytes from the area pointed to by handle, starting from offset, is 
taken into a private memory area. This copy is then passed to the Attribute conversion 
routines to write the new values into. On AspectCallSet calls, the application level set 
function as denoted by the aspect descriptor is called and the private copy (request struc- 
ture) is released afterward. 

3.3.1 Function Type ORM.AspectSetFunc 

This function is called from the aspect layer to actually apply the new attribute values to 
the application layer and/or initiate the requested state changes. This function usually 
should not block, e.g. should not wait until the initiated state change is completed. Any 
kind ot intermediate state should instead be visible to a client on request (i.e. not 
STOPPED *> STARTED, but STOPPED -> STARTING -> STARTED, if starting implies a 
heavier operation. 

Declaration: 

CRM_S^atua 

typeti-*f ; * OR. M ._A * pe c t S-i t F -i n ;: ) { 



* a peer , 
-urccnt , 



•errortext 



/ * 



in ■ / 
in */ 
in • / 
out * / 



l ; 



Fields: 



Ixandle 



the handle as returned from HandleCet 



aspect 



Reference to the aspectdescr. 

Copy \\( the aspect as^de&ribed by the aspectdescr updated with 
new values. 



52 



BNSDOCID: <WO. 



.9802831 A 1_1_> 



WO 98/02831 



PCT/US97/11885 



current 
errortext 

returns 



Reference to aspect within handle 

Where to store a pointer to a short textual description if the 
requested values could NOT be applied. 

ORM.ENoError if all new values could be applied, or 
ORMlEParameterList if paremter set is inconsistent or 
ORN/LEMissingAttribute if a mandatory attribute is NULL. 



3.3.2 The ORM.AspectDescrDef 

This descriptor maintains information about the application data structure (usually refer- 
ences by the ORM_AppHand!e) or parts of it. It describes the binary size, the offset 
within the handlefand contains pointers to functions to actually retrieve or modify this 
aspect of the application instance. 

Note: It is currently open, whether there should be a procedural interface to set up the 
aspect descriptor instead of providing a structure type definition to be passed initialized 
bv the application code 



Declaration: 



:3 : 



7-=: 



? X A *; l ■:: : Z rt : l Tag 
• name ; 
:::£set; 
s.ze; 

0 F M _ A 3 p e r t i e t V u r. c :»ecr; 

1 :ng ippid.; 
vrii *appext; 
I CRM A.5C€c:D«;cr:ef ; 



Fields: 
name 
Offset 

size 

SL'tf 

appext 
appsd 



Pointer to name string, for identification mainly. 

The offset in bytes within the instance, where this aspect starts. 
This usually is the offset of a sub structure in the instance. 

The size in bytes of the instance, the application handle pointer 
points to. For set-requests, the container for the new value is cre- 
ated by copying the handle, and inserting the new values in it. 

If set to ORM.AspectGetlndirect, the offset indicates the offset to a 
pointer, pointing to another structure of the above size. 

Pointer to function, which is called to apply (a set of) new values to 
an application instance. 

any value of pointer size the application wants to store with the 
aspect. This may be used to store a create .aspect function pointer. 

Opaque identifier, which may be used by the applications layer 
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3.4 ORM Attribute Layer 

This section was generated from <stdtn> by CDOC on Fri jan 27 19:59:54 1995. 

The ORM Attribute layer adds another level of ORM application/ server support on top 
of the ORM node layer, by providing (list of) attribute descriptors, which simply initial- 
ized by the application code, allowe automatic conversion and generation of the attribute 
meta information, requested by the ORM protocol layer. 

The implementation of the attribute layer in the ORM SSL assumes, that it is converting 
to and from a binary blob of data, identified by the (lower level) aspect descriptor. The 
goal of this layer is to reduce the coding effort needed by the application writer at this 
layer, just to provide some initialized descriptors and pass them to the ORM SSL via sin- 
gle calls per every instance created. 



3.4.1 The ORM.AttributeDescriptorDef 

This daui structure describes o single attribute, e.g. its native type and mode, its size, 
pointers to conversion functions In addition it maintains hooks for preset meta-info like - 
Unit and R/i/i\v. 



Declaration: 

i ypele :' st:u:t JRtt^At z r :cu: eDesc: 
CR_ M ._;it c ir.q 
- P>1 At n r 1 1 yreP'r f 

v-'.y ^ - - 



- - - t. r.gT iLiveFunc 
C rM_AepC cr.ve;c*rA:;Set 
1 ORMjv- c rifcu teDesc cDe f ; 



a? t 
name; 
datatype ; 

range ; 

off ; 
.uie; 

nativetoatrir.g; 
scringtonative; 
cenvarg; 



Fields: 



name 

nttxie 
range 

urut 



The name of the attribute. 

I lie t> pe of data of this attribute (ORM.AttributeTypeDef). This is 
.i superset of the data types, the ORM protocol defines and used to 
determine implicit conversion routines. 

The allowed access modes of this attribute out of 
ORM.AttribMode values, e.g. read-only, write- only, read-wnte. 

A string describing the allowed ranges for new values for read- 
write or write-only attributes only. This is a ORM hint, and as such 
optional 

A unit string (usually ms, Mb, etc.) which may be used by object 
specific user interface generators in any way, and by default if 
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present is placed behind the attribute value. This is also an ORM 
hint and as such optional. 

conversion function A function pointer to an application specific conversion function, 
to convert between native and ORM presentations. Note: This is 
not to be confused with the similar functions of the ORM_Context 
structure. For the <con version- function> to be called, the 
ORM.Node conversions functions have to be setup in the 
ORM.Context. 

convenion-arg An opaque pointer to any argument, the conversion function may 
need to convert this attribute. 

3.4.2 ORM.AttributeCreare 

This function combines several actions required to register an attribute of a (new) 
instance with the ORM SSL i.e. it creates an attribute node under the given parent (which 
must be of ORM_\odeTypeComponent) and attaches the attribute description and the 
handle information to it. 

Prototype: 

in-. 

; p>! A - r . z . : c~ * t e < 

:?:•! Ar.:;::tu*.e-e3:tListDel 



r-iative, /* in •/ 

relation, / * in * / 

dccri'c-iescr, /' in • / 

espectiescr, / • in • / 

nandle, /* in ■/ 

• r.ew / ■ out • 



Parameters: 



relation 



attribtUncr 
.is/vi 'tM'M'r 
ha nJlc 



pointer to relative node. If relation is set ORMJModelsParent, then 
this has to be a node of ORM.NodeTypeComponent. If relation is 
set to ORM.NodelsSibbling, then this node can be of any valid 
node type. 

Either ORM.NodelsParent, if the node relative should be the par- 
ent of the new attribute node, or ORM_NodeIsSibbling, if the new 
attribute node should be inserted after the relative node as a sib- 
bling. 

No description 
No description 

Pointer to the application instance this attribute belongs to or 
ORM.Handlelnherit (-1), if the handle should be taken from the 
parent (or its parent and so on). 



new 



Pointer to new attribute node or NULL on failure. 
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3.4.3 ORM.AttributeDestroy 

This function detaches the attribute node from the tree of nodes if any, deletes the node 
structure and deletes any depending structures, i.e. the attribute descriptor. 

In the current implementation this function maps directly to ORM_NodeDestroy, but 
nevertheless this function should be called for attribute nodes created with functions of 
this layer to be able to deallocate any dynamic memory. 

Prototype: 

inc 

CR>!_At- r:t.:e:e:: rcy ( OPM_Ncc!eDef atcrncde) ; 
Parameters: 

attrnade Pointer to attrbute node. 



3.4.4 ORM.AttributeListCreate 

This is another convenience functions to add a list of attributes to a component. The 
given node must be a of component type and is used as the parent for the new list of 
attributes ( which is appended to the end of the list of child-nodes). The pointer to the 
attribute descriptor now points to an array of those descriptors, where the end of the 
array is marked by a descriptor whose name pointer is NULL. 

Prototype: 







pa rent , 


/ * 


in 


•/ 






nardl«, 


/• 


in 


• / 






aiipectiescr, 


. / » 


in 


• /' 






attrdescrliat , 


/ • 


in 


•/ 






act recent 


* » 


in 


*/ 



Parameters: 
parent 

handle 



aUrdescrhst 



Pointer to an existing component node, who is the parent node of 
all newly created attribute nodes. 

Pointer to the application instance, all attribute belongs to or 
ORM_HandleInherit (-1), which indicates, that the actual handle is 
determined by the parent (which again may have its handle set to 
ORM.Handlelnherit!) 

No description 

Pointer to an array of ORM.AttributeDescr, with name^NULL in 
the last element if attrcount is < 0. 
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atirciHtitt The number of attribute descriptors in the list or the number of ini- 

tial attributes from this list to attach to this node or -1, if the end of 
the list (array) should be determined by a NULL nodeinfo pointer. 
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3.5 ORM Attribute Conversion Support 

This section was generated from <$tdin> by CDOC on Sun Jan 29 18:13:38 1995. 

This part or the ORM Server Support Layer provides functions for converting generic 
ORM data types between their native (binary) and the ORM (ASCII) presentation. The 
interface between the attribute and the conversion layer is defined by to function types, 
one for converting application native data into an ORM representation, one to convert 
ORM attribute value strings into the applications native presentation. Beside the conver- 
sion functions provided by the ORM-SSL, every application may provide its own special 
converters as long as their interfaces conform these function types. 



3.5.1 Function Type ORM.ConverterNativeToString 

This function is called to convert a single native value into its string representation. In 
addition to the value string it may generate the range and unit strings, if the pointer val- 
ues passed are non-null. If the converter function returns NULL in these pointers, the 
lower (attribute) layer may provide default strings if any. 

Memory Allocation: The memory to hold the converted string vaiue(s) has to be provided 
by the converter function. It is reasonable to use static memory for this purpose, because 
before the converter function is called again, the ORM protocol layer will copy the strings 
returned. 

Declaration: 



-y; 



T<M_ "c r. ve rterNdt i veToSt ringFur.c ) { 



Fields: 
ptr 
size 

datatype 

itrvtUiti* 
st r range 



5i:*_: size, 
C?sM_Ar z ziZuznZ -sscr Li atDef datatype, 

C PM_A?pC o n v e r t e r A r g £ ccnvarg, 

CRM_St ring • st rvalue, 

C RM_ String •strrange, 

C-F»>1_5r. r ir.q •strunit 
) ; 



in 

in 

in 

in 

out 

out 

out 



Address of native data element (e.g. attribute value) 
Byte-size of data element 

One of the ORM_AttributeTypes identifying the type of the native 
data element and its mapping to an ORM Protocol data type (??is 
this overloaded ??) 

Any kind of argument (pointer) for this converter (as provided 
with the attribute descriptor for ex.) 

Where to store the pointer to the converted value string. 

Where to store therfeference to the optional range string 
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ftrunit Where to store the reference to the optional unit string. 

3.5.2 Function Type ORM.ConverterStringToNative 

This function is called to convert a single ORM string value into its native presentation. 
The pointer for the result usually points into a set of different attributes, e.g. an aspect, 
which usually is a (partial) copy of some application data instance. 

Memory Allocation: The destination pointer provided references some valid memory (e.g. 
an aspect), but for references (the native value is a C-string for ex.), there is usually not 
enough space for the referenced value. This space must be allocated/ provided by the 
converter itself It is legal, to reference the original string as passed in to the converter 
function, but then the AspectCallSet function should make a copy, if the string is needed 
beyond this call 

Declaration: 



^ypeJe : :?.M_5:sv;5 ( • ORM_CerwertecSt rir.gTcNac ivefunc ) ( 

c^^Acpr^.trtPrrDcf desc, /• in »/ 

:;2 (i_: size, /' in •/ 

"=>y At : r: r VypeGef datatype, /■ in •/ 

Z?:< A.ypCrr.vertfeiArgOef ccnvarg, /* in •/ 

r:.::c| scrvaiue /• in ■/ 



Fields: 
d est 

max size 
datatype 

itmiluc 
returns 



i 



Address/destination of native data element (e.g. attribute value) 
Maximum byte-size of data element 

One of the ORM.AttributeTypes identifying the type of the native 
data element 

Any kind of data (pointer) for this converter as provided with the 
attribute descriptor 

The new attribute value in its ascii presentation. 

ORM_ENoError if conversion was successfull and the resulting 
attribute value is valid or ORM.ERangeEn-or. 



3.5.3 ORM Built In Conversion Functions 

The following functions are provided to convert generic C datatypes between their ORM 
and their native presentation. In addition sub functions are provided to support the spe- 
cial ORM SELECT and MCHOICE types, which are called by the generic converters. 
Along with these sets two new data structure (types) are introduced. 
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3.5.4 Function ORM JSenericNativeToString 

This function converts standard C-data types into their ASCII presentation. It returns 
only the converted value, but does not support the range and unit parts (e.g. returns 
NULL for those, rf requested). In case of SELECT or MCHOICE functions, this function 
calls the related ORM .Select- or ORM.MChoice functions. 

Note: It is currently open, whether the conversion argument convarg may be used to spec- 
ify a format string a la printf. Furthermore it is currently open, whether a NULL conver- 
sion function in the attribute descriptor should be directed to this (default) function. 

Arguments as for ORM.ConverterNativeToString! 

Prototype: 

OM4_ArpD£ta?t r.*f ptr, /• in ■/ 

maxsise, /• in ■/ 

CR>!_Att licTypeOei - >'P* * 1 ' ir* 9/ 

C p C c r. ve : i c : A : g De i ccnvarq, / * in •/ 

CF,M_S>nr.g * sz rvalue, / ' out •/ 

-P.M Sctir.g • rangevalue, /■ out •/ 

CRM i:r;r.j •struni: /• cut •/ 



\'o parameter descriptions are available. 

3.5.5 Function ORM.GenericStringToNative 

This function converts ASCII C-strings into standard C-datatypes. In case of SELECT or 
MCHOICE functions/ this function calls the related ORM.Select.. or ORM-.MC-hoice 
functions. 

Note: It is currently open, whether the conversion argument convarg may be used to spec- 
ify a format string a la s$ainf. Furthermore it is currently open, whether a NULL conver- 
sion function in the attribute descriptor should be directed to this (default) function. 

Arguments as for ORM.ConverterStringToNativei 

Prototype: 

CRM 3ta- us CSX 'one z icSz ri npToNative ( 



CRM_ AcpDitaPt rOer 


Ptr, 


/ • i n 


• / 


s x ze_i 


iux.3 i ze, 


/ • in 


• / 


:PM_At t r i t Ty peCe i 


type. 


/* in 


•/ 


"• ? y ' . :: p;7 ? r. v c-r:i.T A r 3 D e £ 


ronva rq, 


/• in 


•/ 


^ ^ * i . r.a 


strvilue 


/ • i r. 


■ / 



No parameter descriptions are available. 
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3.5.6 Structure ORM.StringMapDcf 

This type of structure is used to map strings to binary values and vice versa. It may be 
used to convert internal flags and states to friendly names. StringMaps must be termi- 
nated bv an entTv with name set to NULL. 

Declaration: 

type-clef .'-.ruct CSX_St r i r.^V. lpTag ( 

-p-A . ., v <«»y: 

- • ; - ' _ - :. r - r. iXipI e : ; 

Fields: 

name Friendly name for this key. 

key The binary native value of the key 

3.5.7 ORM.StringMapToString 

This function tiwps .i value key to a string using the given StringMap. It returns the string 
of that nvnp entr>. \\ hose key is equal to the given key, else it returns the string passed in 

notfoumi. 

Prototype: 

CR>! St r ir.iy.e.pl r rir.*7 i VH>!_3t ringMep^ef nap, 
:?.M_X.ey key, 
*. itrir.a r.ci round) ; 

Parameters 

mni* Pointer to a sequence of map entries 

key Binary key value. 

notfound string to give back, if none of the keys in the map matched. 

3.5.8 ORM.StringMapToKey 

This function maps a string value to a binary key using the given StringMap. It returns 
the key of that map entry, whose string is equal to the given key, else it returns the key 
passed in unsiiiAkty. 

Prototype: 

CRM_Key 

C fcM_ 3 r r i. : qMa p T c • e y < C ? M _3 1 r i r\q.MapOe f cr-a p , 

CRM^Jtrina name, 
wSM^Koy invali dicey 1 ; 

Parameters: 
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map Pointer to a sequence of map entries 

name No description 

mvalidkey No description 

3.5.9 Structure ORM.StateMapDef 

This structure is used to map states into strings, where a state is assumed to have a distinct 
set of possible next states, depending on the current value. E.g. this structure can be used 
to derive the set of possible new values i.e. it can provide the range value for a state 
attribute. 

Otherwise it is used similar to the simpler StringMap structure. StateMaps must be termi- 
nated by an entry with name set to NULL. 

Declaration 

: v c^-^r t ::^_-;^.:cMa?:ig I r.zz or :rie U.S.A. ! ' •/ 

r: - ; • ame. 
-ro*_.<iy ."EC ace; 

- ?0'._r r r :. :\q vaii cln e :< c 5 ; 
■ * lii eMa pDe f ; 

Fields: 

name Friendly name for this key. 

state The binary native value of this state 

valid next* String of comma separated names of next valid states which may 

follow this state. 

3.5.10 ORM_SlateMapToString 

Convert an encoding of a state into a friendly name using the given statemap. If the state 
could not be found, the string passed in notfound is returned. 

Prototype: 



- r-M y ey s i. a ~ -* t 

CHM_3crin«5 ret found) ; 

Parameters: 



ma P Pointer to a <name=NULL) terminated state map. 

state the binary state 

notfound string to return, if none of the entries in the map had exactly the 

given state key. 



62 



WO 98/02531 



PCT/US97/11885 



3.5.11 ORM.StateMapToKey 

Convert a string representation of a state into a native encoding of a state using the given 
statemap. If the string could not be found, the state passed in mvahdstate is returned. 

Prototype 

CK>i~f i;i' v -rtD:-Key ( CRM_St areKapDef map, 
~ GRM_ Seeing * a me , 

CRM_Key invalidatate) ; 

Parameters: 

map Pointer to a (name=rs/ULL) terminated state map. 

name No description 

invalidstate No description 

3.5.12 ORM.StateMapNextByKey 

Return the comma separated list of valid next states given the current state. 
Prototype: 

CK-V it nr. .3 

C-wTst mMsXapN-i-x: ByKfty ( J". RM_S tat eKa pDe £ map, 

Parameters: 

map Pointer to a (name=r>fULL) terminated state map. 

itate the binary state 
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3.6 ORM Dump & Restore Support 

This section was generated from <stdin> by CDOC on Fri Jan 27 19:59:34 1995. 

This module of the ORM Server Support Library supports the dump and restore of com* 
plete subtrees, and therefore can be used to save the current configuration to a persistant 
storage media (i.e. the MSF Warehouse) and reload it from there. The actual IO functions 
are currently not supported by this layer or the support library at all! 

Dump and Restore are functions of the ORM SSL and not of the ORM protocol (i.e. there 
is no DUMP or RESTORE request defined in the protocol). 

This implies, that these functions have to be dispatched out of the application layer 
explicitly One (intended) way to dispatch those functions interactively is to provide 
pseudo components in every subtree, which should be independent storable/ reloadable. 
These contain the required parameters like Warehouse location or version name as 
attributes An Attribute-Set request to this subtree then results in the execution of the cor- 
responding function. 

Under the layered view of the ORM SSL, these two functions belong to the protocol layer, 
as they use (nearly) the same functionality of the higher layers via upcalls. 

3.6.1 General Model: 

Starting from a given node, which is used as the root of the relevant subtree to dump, all 
component, object links and writable attributes with their meta information are recur- 
sivly extracted relative to the current subtree root. The extended/meta information on 
the persistent media can be used to interprete the stored attributes and apply changes to 
the stored version without the ORM server/application alive but through special clients 
(by an ORM /Warehouse gateway for example). 

The dumped ORM tree can be used to reload the whole subtree at any time, by providing 
the node and call the restore function of the ORM SSL (which is a special kind of Set- 
Request). 

This special kind of SET request creates a new situation, as components (or any new sub- 
tree) may have been created dynamically by the ORM server application on request. On 
the next cold start ot the application, these subtrees do not exist. 

This results in failed lookup requests by the ORM protocol layer, which usually is treated 
as an error (remember: ORM-P has no direct support for object/component creation, but 
this is emulated by sets of writeonly attributes in separate subtrees, i.e. New..). To handle 
this case, the application can provide a special function during application context setup 
to create new instances including the ORM subtree (ORMJsJcxieNotFoundTrapFuncO). 

A parameter is passed to this creation function, which indicates, whether this situation 
was caused by a regular ORM protocol request or by an internally generated restore 
request, so the oppluvuion code can still decide to refuse the creation. 
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3.6.2 ORM.Dump 

This function extracts the ORM entit.es in the subtree pointed to by subtree into the char- 
acter buffer, so it can be used by a later ORM.Restore function (or can be used as a subre- 
quest in a regular ORM protocol request). 

It is the responsibility of the caller to provide a sufficient buffer, which can hold the sub- 
tree information of the given depth! 

Prototype: 



sut>r. re<s , 
deptr., 

what,. 

cut ter ( 
•-:a:vl*=n 



Parameters: 
depth 



li'htlt 



buffer 
maxien 



The root of the subtree to dump. All navigation information is 
saved relative to this node. 

The depth, up to which entities in this subtree should be extracted. 
A depth of 0 means, direct childs of the given sub-root only, i.e. if 
the subtree points to a component node with an attribute node as 
one of its direct children, the name of the attribute would be 
extracted, but not the value or other extended attribute informa- 
tion, if depth=0. A depth of -1 extracts the whole subtree, inde- 
pendent of its depth. 

Is a bitmask, defining what kind of entities should be extracted: 
ORM DumpSetObjects ORM.DumpSetComponents 
ORM~DumpSetAttributes ORM.DumpSetWritable 
ORM~DumpSetDefault = Objects I Components I Writable 
ORMJXimpSetEveryThing = Objects I Components I Attributes 

The address of a character buffer, where to store the extracted 
entity information 

Pointer to the maximum length of this buffer. On return, maxlen 
will contain the number of bytes used in this buffer including the 
C-String AO* terminator. 



3.6.3 ORM.Restore 



Function to reload the saved ORM information into an existing subtree, where at least the 

root of the given subtree has to exist. Note: Because the restore request may 

attribute modifications alreadv performed, an application may want to call ORM.Dump 
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(into a temporary buffer) before actually calling ORM.Restore, to be able to undo th* 
ttal operations. e P ar " 

Prototype: 



Parameters: 
subtree 
buffer 

length 



7 buffer, 
• length 



Node of the subtree to load the management information into, 
pointer to ORM subrequest sequence. 

pointer to length of the request. On return, this will contain the 
number of bytes processed from this request. 
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3.7 ORM SSL Generic Datatypes 

I if ndef _ORM_TYPE_H 
•define ~ORM~TYPE~H 

/• 

• Some generic de t i r.i t i . may become obsolete 

• / 



typecef er.-_- 
~a 1 se , 
True 

i ccclean; 



# if ndef NULL 

•define NULL (void -»0 

#endif 

typedef unsigned Icr.g s:ze_:: 

»deii:.e :?. v ._r::< : : f « e . J (void • ) ( ( s i ze_t ) (base ) ♦ ( size_t ) (of f set ) ) 

»3e:.-e :=.v 1 1 : r . :<> iv::: ■ J.r.ailoc (x) 

* ce : . r e Z RM _: ; :ree(x> 

/ • 

• T.cre CRM specific scuff 
•/ 



/ • 

• How requests and responses are passed to the ORM protocol layer 
■ / 



typedef ".a: 
:yce*c: jr. ar 



• ORM_RequestDef ; 



• The principal type ot every ORM protocol entity, e.g. names and values, 

• but also used rr.cst C-stnr.gs. 

• / 



typedef char •ORM_String; 
/■ 

• Used fzz State-Maps and String Maps as the lookup key 

• / 

:ypc Je t . zuq ;?M_Key; 



/ • 

* The following are various opaque handles. Opaque mainly to the protocol 

* layer but also for the lower of two stacked layers. 

* / 



typedef void • CRM_AppNodeDe £ ; 

typedef void *CRM_AppHandleDef : 

typedef • : RM_A pp A spectDe f ; 

zypezei • I RM_AppDa taft rDe f ; 
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typedec vo;; 
cypedef v 3 ia 
typedef vcid 



• C AM_App A ::r: bDe s c rDe f ; 

• Cf>Ji_AppCa .IContextDef; 

• ORM_AppC r r.ve r t e r A rgDe f . 



valxd Arce-sa T.c=es for an attribute 



cypedef er.j- . 

-R>!_A :::;;,ycce.Mone ( 
CRK_A: : ncMcdeP.w, 
^R.V_A;tr— McdeRC, 
CRMA ctri bMode WO , 
wR.M_A 1 t r i cModeRWP 
i 0R«_At t r i bModeOe i ; 



Known (native) data^ 



ypes, which are supported by the Generic 



-y?ece i e: 
C?.v_A: 
CR.V~A: 



*. ::::y;e.\':r,e . 
' zicTycelr,: 1 , 



^ * - » . — — . 



CRM_At 
CRM "At 
0RM~Ac 
3RM_At 
GRM_At 
CRM^At 
CRM~At 
ORM~At: 
:RM~A-. : 
:n.y~A; : 
w?.M~At Z 
-?>*."" A" * 

or*Ta~ 

ORM~Att 
» CRM A 



crype*-*:r.t2. 
trir?yce: r.t4 , 
tribType'JIr.t 4 , 

- ritType Ir.t 3 , 
-Ticryce'JIr.tS, 
tricType.^eai32, 

- > ibTypeReal 64 , 
" r Type £ i nr.g, 

- - - " Ty c v -ex C C * # 
- " --Typeieiect * 

:-r7yceiiace, 
--oTypeOpticr., 
--DTyceMChoice, 
nbType'JnJcnown 
ttribTypeDef ; 



converter 



i out of many */ 

1 cut of many, but with dynamic range */ 
binary switch ON/orF YES/NO */ 
n out of many */ 



V 8 "" CC " e5 ' " - eil b * Che P«tocoi „ by che orm SSL 



-ypedef erv_.n . 
*-RH_EK?;£r r ? r . 
0RM_EPermi33:cr.. 
ORM_ENo£uchNcde! 

ORM^ENoScchAt tribute 
ORM_ENcSuc*Ob }e:t, 

ORM_EInvalidOpe ration, 
ORM_EProto=oi, 
0RM_EC cwnu r. i c a 1 1 c r. 
3RM_ERar.ge, 

CRM^ENcSoare. 



/ • 
/ * 
/ • 
/ • 
/ * 
/ • 
/ • 



operation successful! ! •/ 
None or wrong auth. information •/ 
some name in pathname could not be found •/ 
in Set - R ^« doesn't •/ 
Object/Manager could not be found-/ 
Operation not applicable to node type •/ 
ORM protocol violation •/ 
lower level comra error •/ 
new attribute value out of range -/ 

m!Llr rt at " ibUteS n0t -PP^cable •/ 
mandatory attrib. missing or NULL •/ 
internal allocation •/ 
response buffer •/ 
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ORM Eintecnal. ' ' ORW Internal error -> bug •/ 

CRfTEApplicaticn, application Level error -> buc •/ 

I CRM Status; 



• - -pes : t -:;es .r. ;^.e ;:;:-al ::ee. Note, that only nodes of type 

* Z?y. n: 2e"/per zr.er.z zsr. r*.ave children! 



typedef enum ( 

GRM_N ode Type Unknown * 
CRM_NodeTypeOb ject , 
CRW_N'cdeTy peCcnpor.ent , 
DRM_Ncde Type Act nfcute, 
CRM McieTy peAr.y 
TRM STdeTypeCef : 



- e ^ - = y cq-eiis. N::e :r.at the Dump and Restore requests are 

• ca— ' zr.-i cut only available within the ORM 

• server supper: . iirary 

• / 

typedef enum * 

CRM_RequestCb:ectGet , 
CRM_RequestCoxponentGet , 
CRM~Req-:estAt t r i cute Get . 
;=>>•"" =< e :te5:A:: ::cjcelr.f oGet , 
Z ->y~? * r •-■;*£' A r - 

CF.M_RequestDump. 
CRM_Requesc Rest ore 
I ORM_Reques^TypeCef ; 



•enai f 
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WHAT IS CLAIMED IS: 

1 • A system for managing objects, including a first server, comprising: 

a first receiver portion configured to receive a request in a 
hypermedia format; 

a first translator portion configured to convert the hypermedia 
request to an object request; 

a sender portion configured to send the object request to an object 

manager; 

a second receiver portion configured to receive a response from 
the object manager; and 

a second translator portion configured to convert the object 
manager response to the hypermedia format. 

2. The system of claim 1, further comprising a second server, including: 
a third receiver portion configured to receive a request in a 
hypermedia format; 

a third translator portion configured to convert the hypermedia 
request to an object request; 

a second sender portion configured to send the object request to 
an object manager; 

a fourth receiver portion configured to receive a response from the 
object manager; and 

a fourth translator portion configured to convert the object - 
manager response to the hypermedia format. 

3. The system of claim 1, further comprising: 

a second sending portion configured to send the hypermedia 
format data from the sender portion to a browser to be displayed. 

4. The system of claim 1, where the object manager manages a self- 

describing object. 

5. The system of claim 1 , where the object manager manages a non-self., 
describing object. 
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6. The system of claim 5, where the object manager performs a "worm" 
function. 

7. A method for browsing objects, where a browser communicates with 
a server, comprising the steps, performed by the browser, of: 

sending an initial URL to the server; 

receiving first data from the server, where the first data specifies 
an object corresponding to the URL; 

sending user-entered data associated with the object to the server; 

and 

receiving second data from the server, where the second data 
specifies a second object corresponding to the user-entered data. 

8. The method of claim 7, 

wherein the step of sending an initial URL to the server comprises 
the step of sending an initial URL known to the browser, where the URL is the 
URL of the server. 

9. The method of claim 7, 

wherein the step of sending an initial URL to the server comprises 
the step of sending an initial URL entered by the user, where the URL is the URL 
of the server. 

10. The method of claim 7, 

wherein the step of sending user-entered data associated with the 
object to the server includes the step of indicating a "set" operation in the user- 
entered data. 

1 1 . The method of claim 7, 

wherein the step of sending user-entered data associated with the 
object to the server includes the step of indicating a "get" operation in the user- 
entered data. 

12. The method of claim 7, wherein the step of receiving second data 
from the server includes the step of receiving data corresponding to an attribute 
value of the object. 
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13. The method of claim 7, wherein the step of receiving second data 
from the server includes the step of receiving data corresponding to a second 
object linked to the first object via an object-link. 

14. A computer program product comprising: 

a computer usable medium having computer readable code 
embodied therein for managing objects, the computer program product 
comprising: 

computer readable program code devices configured to cause a 
computer to effect receiving a request in a hypermedia format; 

computer readable program code devices configured to cause a 
computer to effect converting the hypermedia request to an object request; 

computer readable program code devices configured to cause a 
computer to effect sending the object request to an object manager; 

computer readable program code devices configured to cause a 
computer to effect receiving a response from the object manager; and 

computer readable program code devices configured to cause a 
computer to effect converting the object manager response to a second 
hypermedia format. 

1 5. The computer program product of claim 14, further comprising: 

computer readable program code devices configured to cause a 
computer to effect sending the second hypermedia format data to a browser to 
be displayed. 
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